diff --git a/.asf.yaml b/.asf.yaml new file mode 100644 index 0000000000..a6ab4a8ba6 --- /dev/null +++ b/.asf.yaml @@ -0,0 +1,59 @@ +# 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. + +# https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features +--- +github: + description: "Apache CloudStack is an opensource Infrastructure as a Service (IaaS) cloud computing platform" + homepage: https://cloudstack.apache.org/ + labels: + - iaas + - cloud + - cloudstack + - infrastructure + - java + - python + - kvm + - libvirt + - vsphere + - vmware + - xenserver + - xcp-ng + - orchestration + - virtualization + - virtual-machine + - kubernetes + + features: + wiki: false + issues: false + discussions: false + projects: true + + enabled_merge_buttons: + merge: false + squash: true + rebase: false + + collaborators: + - abh1sar + + protected_branches: ~ + +notifications: + commits: commits@cloudstack.apache.org + pullrequests: commits@cloudstack.apache.org diff --git a/.github/workflows/gen-docs.yaml b/.github/workflows/gen-docs.yaml new file mode 100644 index 0000000000..4588d22c8c --- /dev/null +++ b/.github/workflows/gen-docs.yaml @@ -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. + +name: readthedocs/actions + +on: + pull_request_target: + +permissions: + pull-requests: write + +jobs: + pull-request-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "cloudstack-documentation" diff --git a/.gitignore b/.gitignore index 92e85090da..bd89c3fe36 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ build/ .vscode source/_build/ +/.idea +/.tx diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 12e88e97f5..35a95c185d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,16 @@ version: 2 +sphinx: + configuration: source/conf.py + +build: + os: "ubuntu-22.04" + tools: + python: "3.11" + python: - install: - - requirements: requirements.txt + install: + - requirements: requirements.txt + +sphinx: + configuration: source/conf.py diff --git a/README.rst b/README.rst index 686a01bb98..32f3e50a21 100644 --- a/README.rst +++ b/README.rst @@ -17,7 +17,7 @@ Apache CloudStack ================= -Apache CloudStack is an Apache project, see for +Apache CloudStack is an Apache project - see for more information. @@ -90,7 +90,7 @@ On your computer, follow these steps to setup a local repository for working on .. code:: bash $ git clone https://github.com/YOUR_ACCOUNT/cloudstack-documentation.git - $ cd cloudstack-docs-install + $ cd cloudstack-documentation $ git remote add upstream https://github.com/apache/cloudstack-documentation.git $ git checkout main $ git fetch upstream diff --git a/requirements.txt b/requirements.txt index 93120e66c8..1dbf927199 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1 +1,5 @@ -docutils<0.18 +docutils==0.20.1 +Sphinx==7.2.6 +sphinx-rtd-theme==2.0.0 +readthedocs-sphinx-ext==2.2.5 +Jinja2==3.1.5 diff --git a/source/_global.rst b/source/_global.rst index 82397e946d..92bdf8ed8e 100644 --- a/source/_global.rst +++ b/source/_global.rst @@ -17,33 +17,28 @@ .. This file contain Variables shared across other .rst files in this project -.. _CloudStack Installation Guide: https://docs.cloudstack.apache.org/projects/cloudstack-installation -.. _CloudStack Administrator's Guide: https://docs.cloudstack.apache.org/projects/cloudstack-administration +.. _CloudStack Installation Guide: https://docs.cloudstack.apache.org/en/latest/installguide/index.html +.. _CloudStack Administrator's Guide: https://docs.cloudstack.apache.org/en/latest/adminguide/index.html .. _CloudStack Apidocs: https://cloudstack.apache.org/api.html .. |documentation_home| replace:: https://docs.cloudstack.apache.org/ .. Latest version systemvm template name -.. |sysvm64-version| replace:: 4.16.0 -.. |sysvm64-name-xen| replace:: systemvm-xenserver-4.16.0 -.. |sysvm64-name-kvm| replace:: systemvm-kvm-4.16.0 -.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.16.0 -.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.16.0 -.. |sysvm64-name-ovm| replace:: systemvm-ovm-4.16.0 +.. |sysvm64-version| replace:: 4.22.0 +.. |sysvm64-name-xen| replace:: systemvm-xenserver-4.22.0-x86_64 +.. |sysvm64-name-kvm| replace:: systemvm-kvm-4.22.0-x86_64 +.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.22.0-x86_64 +.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.22.0-x86_64 +.. |sysvm64-name-ovm| replace:: systemvm-ovm-4.22.0-x86_64 .. Latest version systemvm template URL -.. |sysvm64-url-xen| replace:: http://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-xen.vhd.bz2 -.. |sysvm64-url-kvm| replace:: http://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-kvm.qcow2.bz2 -.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-vmware.ova -.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-hyperv.vhd.zip -.. |sysvm64-url-ovm| replace:: http://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-ovm.raw.bz2 - -.. Version specific: 4.5 systemvm template URL -.. |acs45-sysvm64-url-xen| replace:: https://download.cloudstack.org/systemvm/4.5/systemvm64template-4.5-xen.vhd.bz2 -.. |acs45-sysvm64-url-kvm| replace:: https://download.cloudstack.org/systemvm/4.5/systemvm64template-4.5-kvm.qcow2.bz2 -.. |acs45-sysvm64-url-vmware| replace:: https://download.cloudstack.org/systemvm/4.5/systemvm64template-4.5-vmware.ova -.. |acs45-sysvm64-url-hyperv| replace:: https://download.cloudstack.org/systemvm/4.5/systemvm64template-4.5-hyperv.vhd.zip +.. |sysvm64-url-xen| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-x86_64-xen.vhd.bz2 +.. |sysvm64-url-kvm| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-x86_64-kvm.qcow2.bz2 +.. |sysvm64-url-kvm-aarch64| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-aarch64-kvm.qcow2.bz2 +.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-x86_64-vmware.ova +.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-x86_64-hyperv.vhd.zip +.. |sysvm64-url-ovm| replace:: http://download.cloudstack.org/systemvm/4.22/systemvmtemplate-4.22.0-x86_64-ovm.raw.bz2 .. Images diff --git a/source/_static/images/B&R-Backup-Offerings.png b/source/_static/images/B&R-Backup-Offerings.png new file mode 100644 index 0000000000..0d6ba4e83c Binary files /dev/null and b/source/_static/images/B&R-Backup-Offerings.png differ diff --git a/source/_static/images/B&R-Backup-Repository.png b/source/_static/images/B&R-Backup-Repository.png new file mode 100644 index 0000000000..bd53395842 Binary files /dev/null and b/source/_static/images/B&R-Backup-Repository.png differ diff --git a/source/_static/images/B&R-BackupScheduleEntry.png b/source/_static/images/B&R-BackupScheduleEntry.png index 3f5b3392ae..67f73cf85f 100644 Binary files a/source/_static/images/B&R-BackupScheduleEntry.png and b/source/_static/images/B&R-BackupScheduleEntry.png differ diff --git a/source/_static/images/B&R-ConfigureInstance.png b/source/_static/images/B&R-ConfigureInstance.png new file mode 100644 index 0000000000..8712c89943 Binary files /dev/null and b/source/_static/images/B&R-ConfigureInstance.png differ diff --git a/source/_static/images/B&R-CreateInstanceFromBackup.png b/source/_static/images/B&R-CreateInstanceFromBackup.png new file mode 100644 index 0000000000..18ce385683 Binary files /dev/null and b/source/_static/images/B&R-CreateInstanceFromBackup.png differ diff --git a/source/_static/images/B&R-Cross-Zone-Enable-Add.png b/source/_static/images/B&R-Cross-Zone-Enable-Add.png new file mode 100644 index 0000000000..fd50c01038 Binary files /dev/null and b/source/_static/images/B&R-Cross-Zone-Enable-Add.png differ diff --git a/source/_static/images/B&R-Cross-Zone-Select-Zone.png b/source/_static/images/B&R-Cross-Zone-Select-Zone.png new file mode 100644 index 0000000000..efe12598dc Binary files /dev/null and b/source/_static/images/B&R-Cross-Zone-Select-Zone.png differ diff --git a/source/_static/images/BnR-Networker-Cluster-Client-General.jpg b/source/_static/images/BnR-Networker-Cluster-Client-General.jpg new file mode 100755 index 0000000000..7a142014f3 Binary files /dev/null and b/source/_static/images/BnR-Networker-Cluster-Client-General.jpg differ diff --git a/source/_static/images/BnR-Networker-Cluster-Client-Globals1.jpg b/source/_static/images/BnR-Networker-Cluster-Client-Globals1.jpg new file mode 100755 index 0000000000..1fb533a759 Binary files /dev/null and b/source/_static/images/BnR-Networker-Cluster-Client-Globals1.jpg differ diff --git a/source/_static/images/BnR-Networker-Cluster-Client-Globals2.jpg b/source/_static/images/BnR-Networker-Cluster-Client-Globals2.jpg new file mode 100755 index 0000000000..5fcb9b51a1 Binary files /dev/null and b/source/_static/images/BnR-Networker-Cluster-Client-Globals2.jpg differ diff --git a/source/_static/images/BnR-Networker-Cluster-Clients-overview.jpg b/source/_static/images/BnR-Networker-Cluster-Clients-overview.jpg new file mode 100755 index 0000000000..80c4bb2e6d Binary files /dev/null and b/source/_static/images/BnR-Networker-Cluster-Clients-overview.jpg differ diff --git a/source/_static/images/BnR-Networker-MediaPool-Configuration.jpg b/source/_static/images/BnR-Networker-MediaPool-Configuration.jpg new file mode 100755 index 0000000000..6b980fc46b Binary files /dev/null and b/source/_static/images/BnR-Networker-MediaPool-Configuration.jpg differ diff --git a/source/_static/images/BnR-Networker-MediaPool-General.jpg b/source/_static/images/BnR-Networker-MediaPool-General.jpg new file mode 100755 index 0000000000..de4eaafbcb Binary files /dev/null and b/source/_static/images/BnR-Networker-MediaPool-General.jpg differ diff --git a/source/_static/images/BnR-Networker-Policies.jpg b/source/_static/images/BnR-Networker-Policies.jpg new file mode 100755 index 0000000000..2b26069ba5 Binary files /dev/null and b/source/_static/images/BnR-Networker-Policies.jpg differ diff --git a/source/_static/images/BnR-Networker-Policy.jpg b/source/_static/images/BnR-Networker-Policy.jpg new file mode 100755 index 0000000000..df92245b7e Binary files /dev/null and b/source/_static/images/BnR-Networker-Policy.jpg differ diff --git a/source/_static/images/BnR-Networker-clustername.jpg b/source/_static/images/BnR-Networker-clustername.jpg new file mode 100755 index 0000000000..ab3879bda5 Binary files /dev/null and b/source/_static/images/BnR-Networker-clustername.jpg differ diff --git a/source/_static/images/CloudStack-shared-network.png b/source/_static/images/CloudStack-shared-network.png new file mode 100644 index 0000000000..cb87b6a59b Binary files /dev/null and b/source/_static/images/CloudStack-shared-network.png differ diff --git a/source/_static/images/MaaS-add-cluster.png b/source/_static/images/MaaS-add-cluster.png new file mode 100644 index 0000000000..51169322cd Binary files /dev/null and b/source/_static/images/MaaS-add-cluster.png differ diff --git a/source/_static/images/MaaS-add-host.png b/source/_static/images/MaaS-add-host.png new file mode 100644 index 0000000000..11d2934f33 Binary files /dev/null and b/source/_static/images/MaaS-add-host.png differ diff --git a/source/_static/images/MaaS-add-reserve-iprange.png b/source/_static/images/MaaS-add-reserve-iprange.png new file mode 100644 index 0000000000..5451cfe282 Binary files /dev/null and b/source/_static/images/MaaS-add-reserve-iprange.png differ diff --git a/source/_static/images/MaaS-add-sshkeypair.png b/source/_static/images/MaaS-add-sshkeypair.png new file mode 100644 index 0000000000..7711104991 Binary files /dev/null and b/source/_static/images/MaaS-add-sshkeypair.png differ diff --git a/source/_static/images/MaaS-add-subnet-1.png b/source/_static/images/MaaS-add-subnet-1.png new file mode 100644 index 0000000000..a58af418e5 Binary files /dev/null and b/source/_static/images/MaaS-add-subnet-1.png differ diff --git a/source/_static/images/MaaS-add-subnet-2.png b/source/_static/images/MaaS-add-subnet-2.png new file mode 100644 index 0000000000..14ceb50fc2 Binary files /dev/null and b/source/_static/images/MaaS-add-subnet-2.png differ diff --git a/source/_static/images/MaaS-add-template.png b/source/_static/images/MaaS-add-template.png new file mode 100644 index 0000000000..28a3b2715f Binary files /dev/null and b/source/_static/images/MaaS-add-template.png differ diff --git a/source/_static/images/MaaS-add-token.png b/source/_static/images/MaaS-add-token.png new file mode 100644 index 0000000000..c1f79504bb Binary files /dev/null and b/source/_static/images/MaaS-add-token.png differ diff --git a/source/_static/images/MaaS-deploy-instance.png b/source/_static/images/MaaS-deploy-instance.png new file mode 100644 index 0000000000..78d3530f40 Binary files /dev/null and b/source/_static/images/MaaS-deploy-instance.png differ diff --git a/source/_static/images/MaaS-disable-dhcp.png b/source/_static/images/MaaS-disable-dhcp.png new file mode 100644 index 0000000000..9fba0e8525 Binary files /dev/null and b/source/_static/images/MaaS-disable-dhcp.png differ diff --git a/source/_static/images/MaaS-enable-dhcp-on-servers.png b/source/_static/images/MaaS-enable-dhcp-on-servers.png new file mode 100644 index 0000000000..07d7345aee Binary files /dev/null and b/source/_static/images/MaaS-enable-dhcp-on-servers.png differ diff --git a/source/_static/images/MaaS-subnet-configuration.png b/source/_static/images/MaaS-subnet-configuration.png new file mode 100644 index 0000000000..3bcf805c06 Binary files /dev/null and b/source/_static/images/MaaS-subnet-configuration.png differ diff --git a/source/_static/images/NASB&R-quiesceInstance.png b/source/_static/images/NASB&R-quiesceInstance.png new file mode 100644 index 0000000000..3ba79e9cba Binary files /dev/null and b/source/_static/images/NASB&R-quiesceInstance.png differ diff --git a/source/_static/images/account-limits.png b/source/_static/images/account-limits.png new file mode 100644 index 0000000000..63658b1859 Binary files /dev/null and b/source/_static/images/account-limits.png differ diff --git a/source/_static/images/add-Host.png b/source/_static/images/add-Host.png new file mode 100644 index 0000000000..85eaf5ec00 Binary files /dev/null and b/source/_static/images/add-Host.png differ diff --git a/source/_static/images/add-bucket.png b/source/_static/images/add-bucket.png new file mode 100644 index 0000000000..bfbd1f534e Binary files /dev/null and b/source/_static/images/add-bucket.png differ diff --git a/source/_static/images/add-custom-action.png b/source/_static/images/add-custom-action.png new file mode 100644 index 0000000000..4d8362e377 Binary files /dev/null and b/source/_static/images/add-custom-action.png differ diff --git a/source/_static/images/add-guest-ipv6-prefix-form.png b/source/_static/images/add-guest-ipv6-prefix-form.png new file mode 100644 index 0000000000..f436b9edb7 Binary files /dev/null and b/source/_static/images/add-guest-ipv6-prefix-form.png differ diff --git a/source/_static/images/add-guest-network.png b/source/_static/images/add-guest-network.png index 28fd769c6a..1c749a6179 100644 Binary files a/source/_static/images/add-guest-network.png and b/source/_static/images/add-guest-network.png differ diff --git a/source/_static/images/add-guest-os-button.png b/source/_static/images/add-guest-os-button.png new file mode 100644 index 0000000000..3f66eb98fd Binary files /dev/null and b/source/_static/images/add-guest-os-button.png differ diff --git a/source/_static/images/add-guest-os-category.png b/source/_static/images/add-guest-os-category.png new file mode 100644 index 0000000000..fd2a724d4b Binary files /dev/null and b/source/_static/images/add-guest-os-category.png differ diff --git a/source/_static/images/add-guest-os-form.png b/source/_static/images/add-guest-os-form.png new file mode 100644 index 0000000000..435f2f0857 Binary files /dev/null and b/source/_static/images/add-guest-os-form.png differ diff --git a/source/_static/images/add-guest-os-mapping-button.png b/source/_static/images/add-guest-os-mapping-button.png new file mode 100644 index 0000000000..d59a8885b1 Binary files /dev/null and b/source/_static/images/add-guest-os-mapping-button.png differ diff --git a/source/_static/images/add-ipv6-acl-rule-form.png b/source/_static/images/add-ipv6-acl-rule-form.png new file mode 100644 index 0000000000..ae36e640c1 Binary files /dev/null and b/source/_static/images/add-ipv6-acl-rule-form.png differ diff --git a/source/_static/images/add-ipv6-network-offering-form.png b/source/_static/images/add-ipv6-network-offering-form.png new file mode 100644 index 0000000000..fa73ae6382 Binary files /dev/null and b/source/_static/images/add-ipv6-network-offering-form.png differ diff --git a/source/_static/images/add-ipv6-vpc-offering-form.png b/source/_static/images/add-ipv6-vpc-offering-form.png new file mode 100644 index 0000000000..1d9ee59031 Binary files /dev/null and b/source/_static/images/add-ipv6-vpc-offering-form.png differ diff --git a/source/_static/images/add-new-gateway-vpc.png b/source/_static/images/add-new-gateway-vpc.png deleted file mode 100644 index 8e26579b26..0000000000 Binary files a/source/_static/images/add-new-gateway-vpc.png and /dev/null differ diff --git a/source/_static/images/add-new-gateway-vpc2.png b/source/_static/images/add-new-gateway-vpc2.png new file mode 100644 index 0000000000..8962e58e4b Binary files /dev/null and b/source/_static/images/add-new-gateway-vpc2.png differ diff --git a/source/_static/images/add-object-store.png b/source/_static/images/add-object-store.png new file mode 100644 index 0000000000..a0222f7b09 Binary files /dev/null and b/source/_static/images/add-object-store.png differ diff --git a/source/_static/images/add-public-ipv6-range-form.png b/source/_static/images/add-public-ipv6-range-form.png new file mode 100644 index 0000000000..42a7ff08a0 Binary files /dev/null and b/source/_static/images/add-public-ipv6-range-form.png differ diff --git a/source/_static/images/add-remove-sharedfs-network.png b/source/_static/images/add-remove-sharedfs-network.png new file mode 100644 index 0000000000..8ca212de58 Binary files /dev/null and b/source/_static/images/add-remove-sharedfs-network.png differ diff --git a/source/_static/images/add-shared-network.png b/source/_static/images/add-shared-network.png new file mode 100644 index 0000000000..77bffead0b Binary files /dev/null and b/source/_static/images/add-shared-network.png differ diff --git a/source/_static/images/add-user-popup.png b/source/_static/images/add-user-popup.png new file mode 100644 index 0000000000..cb8c6d671e Binary files /dev/null and b/source/_static/images/add-user-popup.png differ diff --git a/source/_static/images/add-vpc.png b/source/_static/images/add-vpc.png index c2a07ed287..58f4384d36 100644 Binary files a/source/_static/images/add-vpc.png and b/source/_static/images/add-vpc.png differ diff --git a/source/_static/images/adding-local-pool-via-ui.png b/source/_static/images/adding-local-pool-via-ui.png new file mode 100644 index 0000000000..2ba2538cab Binary files /dev/null and b/source/_static/images/adding-local-pool-via-ui.png differ diff --git a/source/_static/images/adding-storage-access-group-on-host.png b/source/_static/images/adding-storage-access-group-on-host.png new file mode 100644 index 0000000000..21915abaca Binary files /dev/null and b/source/_static/images/adding-storage-access-group-on-host.png differ diff --git a/source/_static/images/adding-storage-access-group-on-primary-storage.png b/source/_static/images/adding-storage-access-group-on-primary-storage.png new file mode 100644 index 0000000000..23dbb7bcb6 Binary files /dev/null and b/source/_static/images/adding-storage-access-group-on-primary-storage.png differ diff --git a/source/_static/images/admin-change-password-popup.png b/source/_static/images/admin-change-password-popup.png new file mode 100644 index 0000000000..723dcd3c0c Binary files /dev/null and b/source/_static/images/admin-change-password-popup.png differ diff --git a/source/_static/images/autoscale-vmgroup-delete.png b/source/_static/images/autoscale-vmgroup-delete.png new file mode 100644 index 0000000000..21d8177577 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-delete.png differ diff --git a/source/_static/images/autoscale-vmgroup-deploy-parameters.png b/source/_static/images/autoscale-vmgroup-deploy-parameters.png new file mode 100644 index 0000000000..2224052823 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-deploy-parameters.png differ diff --git a/source/_static/images/autoscale-vmgroup-details.png b/source/_static/images/autoscale-vmgroup-details.png new file mode 100644 index 0000000000..56336d1f33 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-details.png differ diff --git a/source/_static/images/autoscale-vmgroup-policy-new.png b/source/_static/images/autoscale-vmgroup-policy-new.png new file mode 100644 index 0000000000..5033102b12 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-policy-new.png differ diff --git a/source/_static/images/autoscale-vmgroup-policy.png b/source/_static/images/autoscale-vmgroup-policy.png new file mode 100644 index 0000000000..87199752f1 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-policy.png differ diff --git a/source/_static/images/autoscale-vmgroup-profile-parameters.png b/source/_static/images/autoscale-vmgroup-profile-parameters.png new file mode 100644 index 0000000000..fbee85ca0b Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-profile-parameters.png differ diff --git a/source/_static/images/autoscale-vmgroup-profile-reset-userdata.png b/source/_static/images/autoscale-vmgroup-profile-reset-userdata.png new file mode 100644 index 0000000000..59fe60bdc5 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-profile-reset-userdata.png differ diff --git a/source/_static/images/autoscale-vmgroup-profile-update.png b/source/_static/images/autoscale-vmgroup-profile-update.png new file mode 100644 index 0000000000..ef5a90035a Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-profile-update.png differ diff --git a/source/_static/images/autoscale-vmgroup-profile.png b/source/_static/images/autoscale-vmgroup-profile.png new file mode 100644 index 0000000000..69024ab72a Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-profile.png differ diff --git a/source/_static/images/autoscale-vmgroup-update.png b/source/_static/images/autoscale-vmgroup-update.png new file mode 100644 index 0000000000..ba8656c834 Binary files /dev/null and b/source/_static/images/autoscale-vmgroup-update.png differ diff --git a/source/_static/images/bucket-details-browser-tab.png b/source/_static/images/bucket-details-browser-tab.png new file mode 100644 index 0000000000..4a4fa15f0b Binary files /dev/null and b/source/_static/images/bucket-details-browser-tab.png differ diff --git a/source/_static/images/built-in-extensions.png b/source/_static/images/built-in-extensions.png new file mode 100644 index 0000000000..8970333a19 Binary files /dev/null and b/source/_static/images/built-in-extensions.png differ diff --git a/source/_static/images/change-offering-for-volume.png b/source/_static/images/change-offering-for-volume.png new file mode 100644 index 0000000000..850a2c1179 Binary files /dev/null and b/source/_static/images/change-offering-for-volume.png differ diff --git a/source/_static/images/change-storage-pool-scope-to-zone.png b/source/_static/images/change-storage-pool-scope-to-zone.png new file mode 100644 index 0000000000..56119d6d8f Binary files /dev/null and b/source/_static/images/change-storage-pool-scope-to-zone.png differ diff --git a/source/_static/images/change-storage-pool-scope-via-ui.png b/source/_static/images/change-storage-pool-scope-via-ui.png new file mode 100644 index 0000000000..1099e3d997 Binary files /dev/null and b/source/_static/images/change-storage-pool-scope-via-ui.png differ diff --git a/source/_static/images/cks-acquire-publicip.png b/source/_static/images/cks-acquire-publicip.png new file mode 100644 index 0000000000..71831b7b70 Binary files /dev/null and b/source/_static/images/cks-acquire-publicip.png differ diff --git a/source/_static/images/cks-addfirewall.png b/source/_static/images/cks-addfirewall.png new file mode 100644 index 0000000000..585e5c2e46 Binary files /dev/null and b/source/_static/images/cks-addfirewall.png differ diff --git a/source/_static/images/cks-addloadbalancer.png b/source/_static/images/cks-addloadbalancer.png new file mode 100644 index 0000000000..ed2f7b4057 Binary files /dev/null and b/source/_static/images/cks-addloadbalancer.png differ diff --git a/source/_static/images/cks-addnode.png b/source/_static/images/cks-addnode.png new file mode 100644 index 0000000000..cabeced27c Binary files /dev/null and b/source/_static/images/cks-addnode.png differ diff --git a/source/_static/images/cks-cni-configuration-cluster-creation.png b/source/_static/images/cks-cni-configuration-cluster-creation.png new file mode 100644 index 0000000000..c445c79166 Binary files /dev/null and b/source/_static/images/cks-cni-configuration-cluster-creation.png differ diff --git a/source/_static/images/cks-cni-configuration-registration-sample.png b/source/_static/images/cks-cni-configuration-registration-sample.png new file mode 100644 index 0000000000..0ce8a6159d Binary files /dev/null and b/source/_static/images/cks-cni-configuration-registration-sample.png differ diff --git a/source/_static/images/cks-create-cluster-additional-settings.png b/source/_static/images/cks-create-cluster-additional-settings.png new file mode 100644 index 0000000000..5136abd955 Binary files /dev/null and b/source/_static/images/cks-create-cluster-additional-settings.png differ diff --git a/source/_static/images/cks-create-cluster-affinity-groups.png b/source/_static/images/cks-create-cluster-affinity-groups.png new file mode 100644 index 0000000000..469e7a250a Binary files /dev/null and b/source/_static/images/cks-create-cluster-affinity-groups.png differ diff --git a/source/_static/images/cks-create-cluster-form.png b/source/_static/images/cks-create-cluster-form.png index ab1102c531..e12bf741c2 100644 Binary files a/source/_static/images/cks-create-cluster-form.png and b/source/_static/images/cks-create-cluster-form.png differ diff --git a/source/_static/images/cks-csi-integration.png b/source/_static/images/cks-csi-integration.png new file mode 100644 index 0000000000..d72fe3bcd0 Binary files /dev/null and b/source/_static/images/cks-csi-integration.png differ diff --git a/source/_static/images/cks-csi-pods.png b/source/_static/images/cks-csi-pods.png new file mode 100644 index 0000000000..f6d54f8d2f Binary files /dev/null and b/source/_static/images/cks-csi-pods.png differ diff --git a/source/_static/images/cks-custom-template-registration.png b/source/_static/images/cks-custom-template-registration.png new file mode 100644 index 0000000000..72ff75fc05 Binary files /dev/null and b/source/_static/images/cks-custom-template-registration.png differ diff --git a/source/_static/images/clone-icon.png b/source/_static/images/clone-icon.png new file mode 100644 index 0000000000..3ab22055f6 Binary files /dev/null and b/source/_static/images/clone-icon.png differ diff --git a/source/_static/images/compute_offering_dailog_with_compute_only_disk_offering.png b/source/_static/images/compute_offering_dailog_with_compute_only_disk_offering.png new file mode 100644 index 0000000000..af6f52a1fa Binary files /dev/null and b/source/_static/images/compute_offering_dailog_with_compute_only_disk_offering.png differ diff --git a/source/_static/images/compute_offering_dailog_with_diskoffering.png b/source/_static/images/compute_offering_dailog_with_diskoffering.png new file mode 100644 index 0000000000..fa0ac654c3 Binary files /dev/null and b/source/_static/images/compute_offering_dailog_with_diskoffering.png differ diff --git a/source/_static/images/compute_offering_dailog_with_lease.png b/source/_static/images/compute_offering_dailog_with_lease.png new file mode 100644 index 0000000000..bf5417c06c Binary files /dev/null and b/source/_static/images/compute_offering_dailog_with_lease.png differ diff --git a/source/_static/images/configure-2fa-action-button.png b/source/_static/images/configure-2fa-action-button.png new file mode 100644 index 0000000000..9697b11a2c Binary files /dev/null and b/source/_static/images/configure-2fa-action-button.png differ diff --git a/source/_static/images/configure-2fa-at-login-page.png b/source/_static/images/configure-2fa-at-login-page.png new file mode 100644 index 0000000000..25c6ee0816 Binary files /dev/null and b/source/_static/images/configure-2fa-at-login-page.png differ diff --git a/source/_static/images/configure-google-2fa-form.png b/source/_static/images/configure-google-2fa-form.png new file mode 100644 index 0000000000..705849d3f5 Binary files /dev/null and b/source/_static/images/configure-google-2fa-form.png differ diff --git a/source/_static/images/configure-staticpin-2fa-form.png b/source/_static/images/configure-staticpin-2fa-form.png new file mode 100644 index 0000000000..0737a1c947 Binary files /dev/null and b/source/_static/images/configure-staticpin-2fa-form.png differ diff --git a/source/_static/images/create-extension.png b/source/_static/images/create-extension.png new file mode 100644 index 0000000000..166d32aa2a Binary files /dev/null and b/source/_static/images/create-extension.png differ diff --git a/source/_static/images/create-sharedfs-admin.png b/source/_static/images/create-sharedfs-admin.png new file mode 100644 index 0000000000..9eec6c5086 Binary files /dev/null and b/source/_static/images/create-sharedfs-admin.png differ diff --git a/source/_static/images/create-sharedfs.png b/source/_static/images/create-sharedfs.png new file mode 100644 index 0000000000..0a34d2aee8 Binary files /dev/null and b/source/_static/images/create-sharedfs.png differ diff --git a/source/_static/images/create-webhook.png b/source/_static/images/create-webhook.png new file mode 100644 index 0000000000..f1f6286f76 Binary files /dev/null and b/source/_static/images/create-webhook.png differ diff --git a/source/_static/images/dbLoadAverages.png b/source/_static/images/dbLoadAverages.png new file mode 100644 index 0000000000..4a0c62ecec Binary files /dev/null and b/source/_static/images/dbLoadAverages.png differ diff --git a/source/_static/images/default-login.png b/source/_static/images/default-login.png new file mode 100644 index 0000000000..882844c6d2 Binary files /dev/null and b/source/_static/images/default-login.png differ diff --git a/source/_static/images/deploy-vm-arch-types.png b/source/_static/images/deploy-vm-arch-types.png new file mode 100644 index 0000000000..ab16eb5d95 Binary files /dev/null and b/source/_static/images/deploy-vm-arch-types.png differ diff --git a/source/_static/images/deploy_instance_advanced_lease.png b/source/_static/images/deploy_instance_advanced_lease.png new file mode 100644 index 0000000000..8949961d71 Binary files /dev/null and b/source/_static/images/deploy_instance_advanced_lease.png differ diff --git a/source/_static/images/deploy_instance_lease_offering.png b/source/_static/images/deploy_instance_lease_offering.png new file mode 100644 index 0000000000..ac56d0805c Binary files /dev/null and b/source/_static/images/deploy_instance_lease_offering.png differ diff --git a/source/_static/images/deployvm_userdata.png b/source/_static/images/deployvm_userdata.png new file mode 100644 index 0000000000..e26c20b698 Binary files /dev/null and b/source/_static/images/deployvm_userdata.png differ diff --git a/source/_static/images/deployvm_userdata_with_variables.png b/source/_static/images/deployvm_userdata_with_variables.png new file mode 100644 index 0000000000..eca47336a5 Binary files /dev/null and b/source/_static/images/deployvm_userdata_with_variables.png differ diff --git a/source/_static/images/disable-2fa.png b/source/_static/images/disable-2fa.png new file mode 100644 index 0000000000..0f1eb4000d Binary files /dev/null and b/source/_static/images/disable-2fa.png differ diff --git a/source/_static/images/disk_offering_dailog.png b/source/_static/images/disk_offering_dailog.png new file mode 100644 index 0000000000..53678dccb6 Binary files /dev/null and b/source/_static/images/disk_offering_dailog.png differ diff --git a/source/_static/images/drs-cluster-settings.png b/source/_static/images/drs-cluster-settings.png new file mode 100644 index 0000000000..28db8add28 Binary files /dev/null and b/source/_static/images/drs-cluster-settings.png differ diff --git a/source/_static/images/drs-cluster-tab.png b/source/_static/images/drs-cluster-tab.png new file mode 100644 index 0000000000..1ec570e9ce Binary files /dev/null and b/source/_static/images/drs-cluster-tab.png differ diff --git a/source/_static/images/drs-plan.png b/source/_static/images/drs-plan.png new file mode 100644 index 0000000000..d68ec71fac Binary files /dev/null and b/source/_static/images/drs-plan.png differ diff --git a/source/_static/images/dynamic-routing-as-number-ranges.png b/source/_static/images/dynamic-routing-as-number-ranges.png new file mode 100644 index 0000000000..882556b796 Binary files /dev/null and b/source/_static/images/dynamic-routing-as-number-ranges.png differ diff --git a/source/_static/images/dynamic-routing-as-numbers.png b/source/_static/images/dynamic-routing-as-numbers.png new file mode 100644 index 0000000000..fb67649020 Binary files /dev/null and b/source/_static/images/dynamic-routing-as-numbers.png differ diff --git a/source/_static/images/dynamic-routing-bgp-peers.png b/source/_static/images/dynamic-routing-bgp-peers.png new file mode 100644 index 0000000000..ad238bd2b5 Binary files /dev/null and b/source/_static/images/dynamic-routing-bgp-peers.png differ diff --git a/source/_static/images/dynamic-routing-change-network-bgp-peers.png b/source/_static/images/dynamic-routing-change-network-bgp-peers.png new file mode 100644 index 0000000000..2184c00bd6 Binary files /dev/null and b/source/_static/images/dynamic-routing-change-network-bgp-peers.png differ diff --git a/source/_static/images/dynamic-routing-change-vpc-bgp-peers.png b/source/_static/images/dynamic-routing-change-vpc-bgp-peers.png new file mode 100644 index 0000000000..9d3f8ce74a Binary files /dev/null and b/source/_static/images/dynamic-routing-change-vpc-bgp-peers.png differ diff --git a/source/_static/images/edit-user-api-key-access.png b/source/_static/images/edit-user-api-key-access.png new file mode 100644 index 0000000000..e36d6400d7 Binary files /dev/null and b/source/_static/images/edit-user-api-key-access.png differ diff --git a/source/_static/images/edit_instance_lease.png b/source/_static/images/edit_instance_lease.png new file mode 100644 index 0000000000..d406cb96e0 Binary files /dev/null and b/source/_static/images/edit_instance_lease.png differ diff --git a/source/_static/images/extension.png b/source/_static/images/extension.png new file mode 100644 index 0000000000..d72c2c9ebd Binary files /dev/null and b/source/_static/images/extension.png differ diff --git a/source/_static/images/extensions.png b/source/_static/images/extensions.png new file mode 100644 index 0000000000..36ada99d89 Binary files /dev/null and b/source/_static/images/extensions.png differ diff --git a/source/_static/images/filter-user-api-key-access.png b/source/_static/images/filter-user-api-key-access.png new file mode 100644 index 0000000000..d474527a47 Binary files /dev/null and b/source/_static/images/filter-user-api-key-access.png differ diff --git a/source/_static/images/force-password-change-login.png b/source/_static/images/force-password-change-login.png new file mode 100644 index 0000000000..7ad2da89f4 Binary files /dev/null and b/source/_static/images/force-password-change-login.png differ diff --git a/source/_static/images/force-password-reset-quick-action.png b/source/_static/images/force-password-reset-quick-action.png new file mode 100644 index 0000000000..2618322e7c Binary files /dev/null and b/source/_static/images/force-password-reset-quick-action.png differ diff --git a/source/_static/images/forgot-password.png b/source/_static/images/forgot-password.png new file mode 100644 index 0000000000..4042434809 Binary files /dev/null and b/source/_static/images/forgot-password.png differ diff --git a/source/_static/images/guest-os-button.png b/source/_static/images/guest-os-button.png new file mode 100644 index 0000000000..c04c265fdf Binary files /dev/null and b/source/_static/images/guest-os-button.png differ diff --git a/source/_static/images/guest-os-categories.png b/source/_static/images/guest-os-categories.png new file mode 100644 index 0000000000..3bb567cf68 Binary files /dev/null and b/source/_static/images/guest-os-categories.png differ diff --git a/source/_static/images/guest-os-details-form.png b/source/_static/images/guest-os-details-form.png new file mode 100644 index 0000000000..4c926371d5 Binary files /dev/null and b/source/_static/images/guest-os-details-form.png differ diff --git a/source/_static/images/guest-os-mapping-button.png b/source/_static/images/guest-os-mapping-button.png new file mode 100644 index 0000000000..e9f85e90c4 Binary files /dev/null and b/source/_static/images/guest-os-mapping-button.png differ diff --git a/source/_static/images/guest-os-mapping-form.png b/source/_static/images/guest-os-mapping-form.png new file mode 100644 index 0000000000..bdea4c6f0b Binary files /dev/null and b/source/_static/images/guest-os-mapping-form.png differ diff --git a/source/_static/images/hyperv-add-cluster.png b/source/_static/images/hyperv-add-cluster.png new file mode 100644 index 0000000000..c1840cd986 Binary files /dev/null and b/source/_static/images/hyperv-add-cluster.png differ diff --git a/source/_static/images/hyperv-add-host.png b/source/_static/images/hyperv-add-host.png new file mode 100644 index 0000000000..4fb1ca717a Binary files /dev/null and b/source/_static/images/hyperv-add-host.png differ diff --git a/source/_static/images/hyperv-add-iso.png b/source/_static/images/hyperv-add-iso.png new file mode 100644 index 0000000000..1f793b1200 Binary files /dev/null and b/source/_static/images/hyperv-add-iso.png differ diff --git a/source/_static/images/hyperv-add-template.png b/source/_static/images/hyperv-add-template.png new file mode 100644 index 0000000000..8cd7360ceb Binary files /dev/null and b/source/_static/images/hyperv-add-template.png differ diff --git a/source/_static/images/import-vm-from-vmware-to-kvm-options.png b/source/_static/images/import-vm-from-vmware-to-kvm-options.png new file mode 100644 index 0000000000..dd54249dc1 Binary files /dev/null and b/source/_static/images/import-vm-from-vmware-to-kvm-options.png differ diff --git a/source/_static/images/import-vm-from-vmware-to-kvm.png b/source/_static/images/import-vm-from-vmware-to-kvm.png new file mode 100644 index 0000000000..891c77057f Binary files /dev/null and b/source/_static/images/import-vm-from-vmware-to-kvm.png differ diff --git a/source/_static/images/import-volume.png b/source/_static/images/import-volume.png new file mode 100644 index 0000000000..7cb12ba633 Binary files /dev/null and b/source/_static/images/import-volume.png differ diff --git a/source/_static/images/ipv6-acl-list.png b/source/_static/images/ipv6-acl-list.png new file mode 100644 index 0000000000..f9fb2bdebf Binary files /dev/null and b/source/_static/images/ipv6-acl-list.png differ diff --git a/source/_static/images/legacy/template-permissions-update-1.png b/source/_static/images/legacy/template-permissions-update-1.png index f1961c13e0..f0bb6923d6 100644 Binary files a/source/_static/images/legacy/template-permissions-update-1.png and b/source/_static/images/legacy/template-permissions-update-1.png differ diff --git a/source/_static/images/legacy/vm-settings-values-dropdown-KVM-list.png b/source/_static/images/legacy/vm-settings-values-dropdown-KVM-list.png index 1302f4ba12..74a241869d 100644 Binary files a/source/_static/images/legacy/vm-settings-values-dropdown-KVM-list.png and b/source/_static/images/legacy/vm-settings-values-dropdown-KVM-list.png differ diff --git a/source/_static/images/list-unmanaged-managed-volumes.png b/source/_static/images/list-unmanaged-managed-volumes.png new file mode 100644 index 0000000000..732d0bb559 Binary files /dev/null and b/source/_static/images/list-unmanaged-managed-volumes.png differ diff --git a/source/_static/images/manage-ipv4-subnets-for-networks.png b/source/_static/images/manage-ipv4-subnets-for-networks.png new file mode 100644 index 0000000000..9d29f99251 Binary files /dev/null and b/source/_static/images/manage-ipv4-subnets-for-networks.png differ diff --git a/source/_static/images/manage-ipv4-subnets-for-zone.png b/source/_static/images/manage-ipv4-subnets-for-zone.png new file mode 100644 index 0000000000..d5959a02b8 Binary files /dev/null and b/source/_static/images/manage-ipv4-subnets-for-zone.png differ diff --git a/source/_static/images/management-server-peers.png b/source/_static/images/management-server-peers.png new file mode 100644 index 0000000000..898cb36352 Binary files /dev/null and b/source/_static/images/management-server-peers.png differ diff --git a/source/_static/images/management-server-statistics.png b/source/_static/images/management-server-statistics.png new file mode 100644 index 0000000000..6f18b33c1a Binary files /dev/null and b/source/_static/images/management-server-statistics.png differ diff --git a/source/_static/images/management-servers-list.png b/source/_static/images/management-servers-list.png new file mode 100644 index 0000000000..57d7a97ca9 Binary files /dev/null and b/source/_static/images/management-servers-list.png differ diff --git a/source/_static/images/netris-isolation-method.png b/source/_static/images/netris-isolation-method.png new file mode 100644 index 0000000000..167544f888 Binary files /dev/null and b/source/_static/images/netris-isolation-method.png differ diff --git a/source/_static/images/netris-provider-config.png b/source/_static/images/netris-provider-config.png new file mode 100644 index 0000000000..33caa93785 Binary files /dev/null and b/source/_static/images/netris-provider-config.png differ diff --git a/source/_static/images/netris-public-ip-pool.png b/source/_static/images/netris-public-ip-pool.png new file mode 100644 index 0000000000..bf1f4e4c06 Binary files /dev/null and b/source/_static/images/netris-public-ip-pool.png differ diff --git a/source/_static/images/netris-sysvm-vr-ip-range.png b/source/_static/images/netris-sysvm-vr-ip-range.png new file mode 100644 index 0000000000..0c6d8ec701 Binary files /dev/null and b/source/_static/images/netris-sysvm-vr-ip-range.png differ diff --git a/source/_static/images/netris-vxlan-range.png b/source/_static/images/netris-vxlan-range.png new file mode 100644 index 0000000000..c5d71331f1 Binary files /dev/null and b/source/_static/images/netris-vxlan-range.png differ diff --git a/source/_static/images/network-details-ipv6-firewall.png b/source/_static/images/network-details-ipv6-firewall.png new file mode 100644 index 0000000000..78133fec65 Binary files /dev/null and b/source/_static/images/network-details-ipv6-firewall.png differ diff --git a/source/_static/images/network-details-upstream-ipv6-routes.png b/source/_static/images/network-details-upstream-ipv6-routes.png new file mode 100644 index 0000000000..f128360800 Binary files /dev/null and b/source/_static/images/network-details-upstream-ipv6-routes.png differ diff --git a/source/_static/images/network-permissions.png b/source/_static/images/network-permissions.png new file mode 100644 index 0000000000..3da9fd550e Binary files /dev/null and b/source/_static/images/network-permissions.png differ diff --git a/source/_static/images/nfs-mount-options-add-primary-storage.png b/source/_static/images/nfs-mount-options-add-primary-storage.png new file mode 100644 index 0000000000..64719244f8 Binary files /dev/null and b/source/_static/images/nfs-mount-options-add-primary-storage.png differ diff --git a/source/_static/images/nfs-mount-options-create-zone-wizard.png b/source/_static/images/nfs-mount-options-create-zone-wizard.png new file mode 100644 index 0000000000..e88b1e7855 Binary files /dev/null and b/source/_static/images/nfs-mount-options-create-zone-wizard.png differ diff --git a/source/_static/images/nfs-mount-options-edit-primary-storage.png b/source/_static/images/nfs-mount-options-edit-primary-storage.png new file mode 100644 index 0000000000..65922014d5 Binary files /dev/null and b/source/_static/images/nfs-mount-options-edit-primary-storage.png differ diff --git a/source/_static/images/nsx-phy-networks.png b/source/_static/images/nsx-phy-networks.png new file mode 100644 index 0000000000..d372f6307a Binary files /dev/null and b/source/_static/images/nsx-phy-networks.png differ diff --git a/source/_static/images/nsx-provider.png b/source/_static/images/nsx-provider.png new file mode 100644 index 0000000000..8002d9c988 Binary files /dev/null and b/source/_static/images/nsx-provider.png differ diff --git a/source/_static/images/nsx-public-traffic.png b/source/_static/images/nsx-public-traffic.png new file mode 100644 index 0000000000..77e16931eb Binary files /dev/null and b/source/_static/images/nsx-public-traffic.png differ diff --git a/source/_static/images/oauth-configuration-details.png b/source/_static/images/oauth-configuration-details.png new file mode 100644 index 0000000000..fb9cc4d21f Binary files /dev/null and b/source/_static/images/oauth-configuration-details.png differ diff --git a/source/_static/images/oauth-login.png b/source/_static/images/oauth-login.png new file mode 100644 index 0000000000..acc3bac007 Binary files /dev/null and b/source/_static/images/oauth-login.png differ diff --git a/source/_static/images/oauth-provider-registration.png b/source/_static/images/oauth-provider-registration.png new file mode 100644 index 0000000000..81cc5c77d0 Binary files /dev/null and b/source/_static/images/oauth-provider-registration.png differ diff --git a/source/_static/images/oauth-sub-section.png b/source/_static/images/oauth-sub-section.png new file mode 100644 index 0000000000..1cef614d1a Binary files /dev/null and b/source/_static/images/oauth-sub-section.png differ diff --git a/source/_static/images/object-store-browser-tab.png b/source/_static/images/object-store-browser-tab.png new file mode 100644 index 0000000000..45d5e88f1e Binary files /dev/null and b/source/_static/images/object-store-browser-tab.png differ diff --git a/source/_static/images/object-store-file-properties.png b/source/_static/images/object-store-file-properties.png new file mode 100644 index 0000000000..93ae8070ae Binary files /dev/null and b/source/_static/images/object-store-file-properties.png differ diff --git a/source/_static/images/object-store-file-upload.png b/source/_static/images/object-store-file-upload.png new file mode 100644 index 0000000000..f7cdcf8c13 Binary files /dev/null and b/source/_static/images/object-store-file-upload.png differ diff --git a/source/_static/images/plugin1.jpg b/source/_static/images/plugin1.jpg deleted file mode 100644 index 970233d847..0000000000 Binary files a/source/_static/images/plugin1.jpg and /dev/null differ diff --git a/source/_static/images/plugin2.jpg b/source/_static/images/plugin2.jpg deleted file mode 100644 index 9c8a6107ba..0000000000 Binary files a/source/_static/images/plugin2.jpg and /dev/null differ diff --git a/source/_static/images/plugin3.jpg b/source/_static/images/plugin3.jpg deleted file mode 100644 index 07fae790e2..0000000000 Binary files a/source/_static/images/plugin3.jpg and /dev/null differ diff --git a/source/_static/images/plugin4.png b/source/_static/images/plugin4.png deleted file mode 100644 index 8cf28beed1..0000000000 Binary files a/source/_static/images/plugin4.png and /dev/null differ diff --git a/source/_static/images/plugin_intro.png b/source/_static/images/plugin_intro.png deleted file mode 100644 index f166e3b14a..0000000000 Binary files a/source/_static/images/plugin_intro.png and /dev/null differ diff --git a/source/_static/images/primary-storage-file-browser.png b/source/_static/images/primary-storage-file-browser.png new file mode 100644 index 0000000000..066e6db64d Binary files /dev/null and b/source/_static/images/primary-storage-file-browser.png differ diff --git a/source/_static/images/proxmox-add-cluster.png b/source/_static/images/proxmox-add-cluster.png new file mode 100644 index 0000000000..53e91bf890 Binary files /dev/null and b/source/_static/images/proxmox-add-cluster.png differ diff --git a/source/_static/images/proxmox-add-host.png b/source/_static/images/proxmox-add-host.png new file mode 100644 index 0000000000..f251ab3b7c Binary files /dev/null and b/source/_static/images/proxmox-add-host.png differ diff --git a/source/_static/images/proxmox-add-iso.png b/source/_static/images/proxmox-add-iso.png new file mode 100644 index 0000000000..219f89c164 Binary files /dev/null and b/source/_static/images/proxmox-add-iso.png differ diff --git a/source/_static/images/proxmox-add-template.png b/source/_static/images/proxmox-add-template.png new file mode 100644 index 0000000000..dc14d1ef39 Binary files /dev/null and b/source/_static/images/proxmox-add-template.png differ diff --git a/source/_static/images/proxmox-add-token.png b/source/_static/images/proxmox-add-token.png new file mode 100644 index 0000000000..313394c527 Binary files /dev/null and b/source/_static/images/proxmox-add-token.png differ diff --git a/source/_static/images/proxmox-api-token-permission.png b/source/_static/images/proxmox-api-token-permission.png new file mode 100644 index 0000000000..e9a77e3a28 Binary files /dev/null and b/source/_static/images/proxmox-api-token-permission.png differ diff --git a/source/_static/images/proxmox-deploy-instance.png b/source/_static/images/proxmox-deploy-instance.png new file mode 100644 index 0000000000..78a067bb0e Binary files /dev/null and b/source/_static/images/proxmox-deploy-instance.png differ diff --git a/source/_static/images/register_userdata.png b/source/_static/images/register_userdata.png new file mode 100644 index 0000000000..43ca382cc9 Binary files /dev/null and b/source/_static/images/register_userdata.png differ diff --git a/source/_static/images/register_userdata_with_variables.png b/source/_static/images/register_userdata_with_variables.png new file mode 100644 index 0000000000..9a53515cdd Binary files /dev/null and b/source/_static/images/register_userdata_with_variables.png differ diff --git a/source/_static/images/reset-password.png b/source/_static/images/reset-password.png new file mode 100644 index 0000000000..61f2f49b87 Binary files /dev/null and b/source/_static/images/reset-password.png differ diff --git a/source/_static/images/restart-sharedfs.png b/source/_static/images/restart-sharedfs.png new file mode 100644 index 0000000000..84981f330d Binary files /dev/null and b/source/_static/images/restart-sharedfs.png differ diff --git a/source/_static/images/routed-add-network-cidrsize.png b/source/_static/images/routed-add-network-cidrsize.png new file mode 100644 index 0000000000..2782ab1683 Binary files /dev/null and b/source/_static/images/routed-add-network-cidrsize.png differ diff --git a/source/_static/images/routed-add-network-offering.png b/source/_static/images/routed-add-network-offering.png new file mode 100644 index 0000000000..6a27164909 Binary files /dev/null and b/source/_static/images/routed-add-network-offering.png differ diff --git a/source/_static/images/routed-add-vpc-offering.png b/source/_static/images/routed-add-vpc-offering.png new file mode 100644 index 0000000000..120d36151c Binary files /dev/null and b/source/_static/images/routed-add-vpc-offering.png differ diff --git a/source/_static/images/routed-ipv4-routes.png b/source/_static/images/routed-ipv4-routes.png new file mode 100644 index 0000000000..bcb4b3c61e Binary files /dev/null and b/source/_static/images/routed-ipv4-routes.png differ diff --git a/source/_static/images/routed-ipv4-routing-firewall.png b/source/_static/images/routed-ipv4-routing-firewall.png new file mode 100644 index 0000000000..30be661ea6 Binary files /dev/null and b/source/_static/images/routed-ipv4-routing-firewall.png differ diff --git a/source/_static/images/run-custom-action-instance.png b/source/_static/images/run-custom-action-instance.png new file mode 100644 index 0000000000..9da4e9e545 Binary files /dev/null and b/source/_static/images/run-custom-action-instance.png differ diff --git a/source/_static/images/run-custom-action.png b/source/_static/images/run-custom-action.png new file mode 100644 index 0000000000..ae7a10c14c Binary files /dev/null and b/source/_static/images/run-custom-action.png differ diff --git a/source/_static/images/secondary-storage-file-browser.png b/source/_static/images/secondary-storage-file-browser.png new file mode 100644 index 0000000000..3e575c97bb Binary files /dev/null and b/source/_static/images/secondary-storage-file-browser.png differ diff --git a/source/_static/images/sharedfs-access-tab.png b/source/_static/images/sharedfs-access-tab.png new file mode 100644 index 0000000000..97d9b088f3 Binary files /dev/null and b/source/_static/images/sharedfs-access-tab.png differ diff --git a/source/_static/images/ssl-certificate-account.png b/source/_static/images/ssl-certificate-account.png new file mode 100644 index 0000000000..78e2dc018f Binary files /dev/null and b/source/_static/images/ssl-certificate-account.png differ diff --git a/source/_static/images/ssl-certificate-list.png b/source/_static/images/ssl-certificate-list.png new file mode 100644 index 0000000000..5aa3fe74c1 Binary files /dev/null and b/source/_static/images/ssl-certificate-list.png differ diff --git a/source/_static/images/ssl-certificate-new-lb-rule-select.png b/source/_static/images/ssl-certificate-new-lb-rule-select.png new file mode 100644 index 0000000000..682a96172c Binary files /dev/null and b/source/_static/images/ssl-certificate-new-lb-rule-select.png differ diff --git a/source/_static/images/ssl-certificate-new-lb-rule.png b/source/_static/images/ssl-certificate-new-lb-rule.png new file mode 100644 index 0000000000..7dd5043744 Binary files /dev/null and b/source/_static/images/ssl-certificate-new-lb-rule.png differ diff --git a/source/_static/images/ssl-certificate-project.png b/source/_static/images/ssl-certificate-project.png new file mode 100644 index 0000000000..ff97b318ac Binary files /dev/null and b/source/_static/images/ssl-certificate-project.png differ diff --git a/source/_static/images/ssl-certificate-update-lb-rule-protocol.png b/source/_static/images/ssl-certificate-update-lb-rule-protocol.png new file mode 100644 index 0000000000..e6637e57c9 Binary files /dev/null and b/source/_static/images/ssl-certificate-update-lb-rule-protocol.png differ diff --git a/source/_static/images/ssl-certificate-update-lb-rule-ssl-cert.png b/source/_static/images/ssl-certificate-update-lb-rule-ssl-cert.png new file mode 100644 index 0000000000..183c89ee8a Binary files /dev/null and b/source/_static/images/ssl-certificate-update-lb-rule-ssl-cert.png differ diff --git a/source/_static/images/ssl-certificate-upload.png b/source/_static/images/ssl-certificate-upload.png new file mode 100644 index 0000000000..52eef23423 Binary files /dev/null and b/source/_static/images/ssl-certificate-upload.png differ diff --git a/source/_static/images/template-upload-from-local.png b/source/_static/images/template-upload-from-local.png index 27b477c9df..d1632ea6d0 100644 Binary files a/source/_static/images/template-upload-from-local.png and b/source/_static/images/template-upload-from-local.png differ diff --git a/source/_static/images/ui-announcement-banner.png b/source/_static/images/ui-announcement-banner.png new file mode 100644 index 0000000000..fc687f3fe0 Binary files /dev/null and b/source/_static/images/ui-announcement-banner.png differ diff --git a/source/_static/images/ui-legacy-image-selection.png b/source/_static/images/ui-legacy-image-selection.png new file mode 100644 index 0000000000..828800a990 Binary files /dev/null and b/source/_static/images/ui-legacy-image-selection.png differ diff --git a/source/_static/images/ui-login-project-view.png b/source/_static/images/ui-login-project-view.png new file mode 100644 index 0000000000..49299ffd4f Binary files /dev/null and b/source/_static/images/ui-login-project-view.png differ diff --git a/source/_static/images/ui-modern-image-selection.png b/source/_static/images/ui-modern-image-selection.png new file mode 100644 index 0000000000..2fe012593a Binary files /dev/null and b/source/_static/images/ui-modern-image-selection.png differ diff --git a/source/_static/images/unmanage-volume.png b/source/_static/images/unmanage-volume.png new file mode 100644 index 0000000000..7c00686f69 Binary files /dev/null and b/source/_static/images/unmanage-volume.png differ diff --git a/source/_static/images/upload-button.png b/source/_static/images/upload-button.png new file mode 100644 index 0000000000..eb78b81a8e Binary files /dev/null and b/source/_static/images/upload-button.png differ diff --git a/source/_static/images/upload-iso-from-local.png b/source/_static/images/upload-iso-from-local.png index ea0b9e2eff..19e8c175d5 100644 Binary files a/source/_static/images/upload-iso-from-local.png and b/source/_static/images/upload-iso-from-local.png differ diff --git a/source/_static/images/user-change-password-popup.png b/source/_static/images/user-change-password-popup.png new file mode 100644 index 0000000000..1f392195c9 Binary files /dev/null and b/source/_static/images/user-change-password-popup.png differ diff --git a/source/_static/images/user-domain-login.png b/source/_static/images/user-domain-login.png new file mode 100644 index 0000000000..b73779ff7e Binary files /dev/null and b/source/_static/images/user-domain-login.png differ diff --git a/source/_static/images/userdata_template_link.png b/source/_static/images/userdata_template_link.png new file mode 100644 index 0000000000..1db5005461 Binary files /dev/null and b/source/_static/images/userdata_template_link.png differ diff --git a/source/_static/images/verify-2fa-staticpin.png b/source/_static/images/verify-2fa-staticpin.png new file mode 100644 index 0000000000..468140ee51 Binary files /dev/null and b/source/_static/images/verify-2fa-staticpin.png differ diff --git a/source/_static/images/verify-2fa-totp.png b/source/_static/images/verify-2fa-totp.png new file mode 100644 index 0000000000..23b3f694d0 Binary files /dev/null and b/source/_static/images/verify-2fa-totp.png differ diff --git a/source/_static/images/view-guest-os-mappings-button.png b/source/_static/images/view-guest-os-mappings-button.png new file mode 100644 index 0000000000..158c039919 Binary files /dev/null and b/source/_static/images/view-guest-os-mappings-button.png differ diff --git a/source/_static/images/vm-disk-metrics-ui.png b/source/_static/images/vm-disk-metrics-ui.png new file mode 100644 index 0000000000..a773471fdb Binary files /dev/null and b/source/_static/images/vm-disk-metrics-ui.png differ diff --git a/source/_static/images/vm-metrics-ui.png b/source/_static/images/vm-metrics-ui.png new file mode 100644 index 0000000000..3ddbba5c7d Binary files /dev/null and b/source/_static/images/vm-metrics-ui.png differ diff --git a/source/_static/images/vm-schedule-form.png b/source/_static/images/vm-schedule-form.png new file mode 100644 index 0000000000..f49fd8ea6a Binary files /dev/null and b/source/_static/images/vm-schedule-form.png differ diff --git a/source/_static/images/vm-schedule-tab.png b/source/_static/images/vm-schedule-tab.png new file mode 100644 index 0000000000..9fe8ec4d31 Binary files /dev/null and b/source/_static/images/vm-schedule-tab.png differ diff --git a/source/_static/images/vm-settings-kvm-guest-cpu-model.png b/source/_static/images/vm-settings-kvm-guest-cpu-model.png new file mode 100644 index 0000000000..f2f69b4b78 Binary files /dev/null and b/source/_static/images/vm-settings-kvm-guest-cpu-model.png differ diff --git a/source/_static/images/vm-settings-uefi-secure.png b/source/_static/images/vm-settings-uefi-secure.png new file mode 100644 index 0000000000..6e5e4e4810 Binary files /dev/null and b/source/_static/images/vm-settings-uefi-secure.png differ diff --git a/source/_static/images/vm-settings-virtual-tpm-enabled-vmware.png b/source/_static/images/vm-settings-virtual-tpm-enabled-vmware.png new file mode 100644 index 0000000000..7f8d4fe2b0 Binary files /dev/null and b/source/_static/images/vm-settings-virtual-tpm-enabled-vmware.png differ diff --git a/source/_static/images/vm-settings-virtual-tpm-model-kvm.png b/source/_static/images/vm-settings-virtual-tpm-model-kvm.png new file mode 100644 index 0000000000..9075eb57b8 Binary files /dev/null and b/source/_static/images/vm-settings-virtual-tpm-model-kvm.png differ diff --git a/source/_static/images/vm-settings-virtual-tpm-version-kvm.png b/source/_static/images/vm-settings-virtual-tpm-version-kvm.png new file mode 100644 index 0000000000..64bbaba46f Binary files /dev/null and b/source/_static/images/vm-settings-virtual-tpm-version-kvm.png differ diff --git a/source/_static/images/vmware-increase-ports.png b/source/_static/images/vmware-increase-ports.png index fe96815326..013fab1dd6 100644 Binary files a/source/_static/images/vmware-increase-ports.png and b/source/_static/images/vmware-increase-ports.png differ diff --git a/source/_static/images/vmware-nexus-add-cluster.png b/source/_static/images/vmware-nexus-add-cluster.png index 7c1dd73f77..9ba38716df 100644 Binary files a/source/_static/images/vmware-nexus-add-cluster.png and b/source/_static/images/vmware-nexus-add-cluster.png differ diff --git a/source/_static/images/vmware-physical-network.png b/source/_static/images/vmware-physical-network.png index a7495c77b1..d2d287fc53 100644 Binary files a/source/_static/images/vmware-physical-network.png and b/source/_static/images/vmware-physical-network.png differ diff --git a/source/_static/images/vnf-add-detail.png b/source/_static/images/vnf-add-detail.png new file mode 100644 index 0000000000..9554e83c84 Binary files /dev/null and b/source/_static/images/vnf-add-detail.png differ diff --git a/source/_static/images/vnf-add-nic.png b/source/_static/images/vnf-add-nic.png new file mode 100644 index 0000000000..1dd96cfe56 Binary files /dev/null and b/source/_static/images/vnf-add-nic.png differ diff --git a/source/_static/images/vnf-appliance-networks-selection.png b/source/_static/images/vnf-appliance-networks-selection.png new file mode 100644 index 0000000000..828a89a8ef Binary files /dev/null and b/source/_static/images/vnf-appliance-networks-selection.png differ diff --git a/source/_static/images/vnf-appliance-vnf-nics.png b/source/_static/images/vnf-appliance-vnf-nics.png new file mode 100644 index 0000000000..fd327c8953 Binary files /dev/null and b/source/_static/images/vnf-appliance-vnf-nics.png differ diff --git a/source/_static/images/vnf-details-list.png b/source/_static/images/vnf-details-list.png new file mode 100644 index 0000000000..1f069fd83e Binary files /dev/null and b/source/_static/images/vnf-details-list.png differ diff --git a/source/_static/images/vnf-nics-list.png b/source/_static/images/vnf-nics-list.png new file mode 100644 index 0000000000..4e0dda3172 Binary files /dev/null and b/source/_static/images/vnf-nics-list.png differ diff --git a/source/_static/images/vnf-template-vnf-settings.png b/source/_static/images/vnf-template-vnf-settings.png new file mode 100644 index 0000000000..2a03d1317d Binary files /dev/null and b/source/_static/images/vnf-template-vnf-settings.png differ diff --git a/source/_static/images/volume-metrics.png b/source/_static/images/volume-metrics.png new file mode 100644 index 0000000000..c857260276 Binary files /dev/null and b/source/_static/images/volume-metrics.png differ diff --git a/source/_static/images/webhook-deliveries.png b/source/_static/images/webhook-deliveries.png new file mode 100644 index 0000000000..bb49ffb20d Binary files /dev/null and b/source/_static/images/webhook-deliveries.png differ diff --git a/source/_static/images/webhooks.png b/source/_static/images/webhooks.png new file mode 100644 index 0000000000..b8e9ed5c31 Binary files /dev/null and b/source/_static/images/webhooks.png differ diff --git a/source/_static/images/zone-capacities.png b/source/_static/images/zone-capacities.png new file mode 100644 index 0000000000..f218a40681 Binary files /dev/null and b/source/_static/images/zone-capacities.png differ diff --git a/source/_static/images/zone-kvm-register-template.png b/source/_static/images/zone-kvm-register-template.png new file mode 100644 index 0000000000..62948349bd Binary files /dev/null and b/source/_static/images/zone-kvm-register-template.png differ diff --git a/source/_static/images/zone-register-templates.png b/source/_static/images/zone-register-templates.png new file mode 100644 index 0000000000..438da7befb Binary files /dev/null and b/source/_static/images/zone-register-templates.png differ diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index a7e699a97d..b70515c0e9 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -20,10 +20,10 @@ Roles, Accounts, Users, and Domains Roles ~~~~~ -A role represents a set of allowed functions. All CloudStack accounts have a +A role represents a set of allowed functions. All CloudStack Accounts have a role attached to them that enforce access rules on them to be allowed or disallowed to make an API request. Typically there are four default roles: -root admin, resource admin, domain admin and user. +root admin, resource admin, domain admin and User. Newer roles have been added which include Read-Only Admin, Read-Only User, Support Admin and Support User which are in turn based on the aforementioned roles. @@ -31,48 +31,50 @@ Support Admin and Support User which are in turn based on the aforementioned rol Accounts ~~~~~~~~ -An account typically represents a customer of the service provider or a -department in a large organization. Multiple users can exist in an -account. +An Account typically represents a customer of the service provider or a +department in a large organization. Multiple Users can exist in an +Account. Domains ~~~~~~~ Accounts are grouped by domains. Domains usually contain multiple -accounts that have some logical relationship to each other and a set of +Accounts that have some logical relationship to each other and a set of delegated administrators with some authority over the domain and its subdomains. For example, a service provider with several resellers could create a domain for each reseller. -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. +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: + Users ~~~~~ -Users are like aliases in the account. Users in the same account are not -isolated from each other, but they are isolated from users in other -accounts. Most installations need not surface the notion of users; they -just have one user per account. The same user cannot belong to multiple -accounts. +Users are like aliases in the Account. Users in the same Account are not +isolated from each other, but they are isolated from Users in other +Accounts. Most installations need not surface the notion of Users; they +just have one User per Account. The same User cannot belong to multiple +Accounts. -Username is unique in a domain across accounts in that domain. The same +Username is unique in a domain across Accounts in that domain. The same username can exist in other domains, including sub-domains. Domain name can repeat only if the full pathname from root is unique. For example, you can create root/d1, as well as root/foo/d1, and root/sales/d1. -Administrators are accounts with special privileges in the system. There +Administrators are Accounts with special privileges in the system. There may be multiple administrators in the system. Administrators can create -or delete other administrators, and change the password for any user in +or delete other administrators, and change the password for any User in the system. Domain Administrators ~~~~~~~~~~~~~~~~~~~~~ -Domain administrators can perform administrative operations for users +Domain administrators can perform administrative operations for Users who belong to that domain. Domain administrators do not have visibility into physical servers or other domains. @@ -81,49 +83,49 @@ Root Administrator ~~~~~~~~~~~~~~~~~~ Root administrators have complete access to the system, including -managing templates, service offerings, customer care administrators, and +managing Templates, service offerings, customer care administrators, and domains Read Only Administrator ~~~~~~~~~~~~~~~~~~~~~~~ -A restricted admin role in which an account is only allowed to perform any list, get +A restricted admin role in which an Account is only allowed to perform any list, get or find operations but not perform any other operation which can change the -infrastructure, configuration or user resources. +infrastructure, configuration or User resources. Read Only User ~~~~~~~~~~~~~~ -A restricted user role in which an account is only allowed to perform list, get or find -operations. It can be used by users who may only be interested in monitoring and usage +A restricted User role in which an Account is only allowed to perform list, get or find +operations. It can be used by Users who may only be interested in monitoring and usage of resources. Support Admin ~~~~~~~~~~~~~ -A restricted admin role in which an admin account is limited to perform axilary support -and maintenance tasks which do not directly affect the infrastucture, such as creating offerings, +A restricted admin role in which an admin Account is limited to perform auxiliary support +and maintenance tasks which do not directly affect the infrastructure, such as creating offerings, and put resources in maintenance, but cannot change the infrastructure such as physical networks. Support User ~~~~~~~~~~~~ -A restricted user role in which an account cannot create or destroy resources, but can view resources -and perform auxilary and support operations such as start or stop VMs, attach or detach volumes, ISOs etc. +A restricted User role in which an Account cannot create or destroy resources, but can view resources +and perform auxiliary and support operations such as start or stop Instances, attach or detach volumes, ISOs etc. Resource Ownership ~~~~~~~~~~~~~~~~~~ -Resources belong to the account, not individual users in that account. +Resources belong to the Account, not individual Users in that Account. For example, billing, resource limits, and so on are maintained by the -account, not the users. A user can operate on any resource in the -account provided the user has privileges for that operation. The +Account, not the Users. A User can operate on any resource in the +Account provided the User has privileges for that operation. The privileges are determined by the role. A root administrator can change -the ownership of any virtual machine from one account to any other -account by using the assignVirtualMachine API. A domain or sub-domain -administrator can do the same for VMs within the domain from one account -to any other account in the domain or any of its sub-domains. +the ownership of any Instance from one Account to any other +Account by using the assignVirtualMachine API. A domain or sub-domain +administrator can do the same for Instances within the domain from one Account +to any other Account in the domain or any of its sub-domains. .. _using-dynamics-roles: @@ -135,8 +137,24 @@ allows CloudStack root admins to create new roles with customized permissions. The allow/deny rules can be configured dynamically during runtime without restarting the management server(s). -For backward compatiblity, all roles resolve to one of the four role types: -admin, resource admin, domain admin and user. A new role can be created using +.. Note:: in versions before 4.16.1, any User given the custom roles + that include permission to create and/or update Accounts + will have the ability to assign new custom roles to + themselves or other Users, irrespective of the privileges + given in those roles. This could allow such a User to + escalate their own privileges to include any API they might + not have had before. Therefore, the dynamic roles should be + carefully designed and the `createAccount` and + `updateAccount` privileges should only be given to Users who + you are content to have this level of privilege. + + Since 4.16.1 a User will be prevented to create an Account + with a role that has any permissions that they do not have + themselves. This check will also be performed, since that + version, on updating an Account-role. + +For backward compatibility, all roles resolve to one of the four role types: +admin, resource admin, domain admin and User. A new role can be created using the roles tab in the UI and specifying a name, either a role type or ID of existing role, and optionally a description. When a new role is created using ID of existing role, all the rules of the existing role are copied to the new role and these rules @@ -159,16 +177,16 @@ CSV file format: … so on -When a user makes an API request, the backend checks the requested API against +When a User makes an API request, the backend checks the requested API against configured rules (in the order the rules were configured) for the caller -user-account's role. It will iterate through the rules and would allow the +User-Account's role. It will iterate through the rules and would allow the API request if the API matches an allow rule, else if it matches a deny rule it would deny the request. Next, if the request API fails to match any of the configured rules it would allow if the requested API's default authorized -annotaions allow that user role type and finally deny the user API request +annotations allow that User role type and finally deny the User API request if it fails to be explicitly allowed/denied by the role permission rules or the default API authorize annotations. Note: to avoid root admin being locked -out of the system, all root admin accounts are allowed all APIs. +out of the system, all root admin Accounts are allowed all APIs. The dynamic-roles feature is enabled by default only for all new CloudStack installations since version `4.9.x `_. @@ -228,27 +246,27 @@ Dedicating Resources to Accounts and Domains -------------------------------------------- The root administrator can dedicate resources to a specific domain or -account that needs private infrastructure for additional security or +Account that needs private infrastructure for additional security or performance guarantees. A zone, pod, cluster, or host can be reserved by -the root administrator for a specific domain or account. Only users in +the root administrator for a specific domain or Account. Only Users in that domain or its subdomain may use the infrastructure. For example, -only users in a given domain can create guests in a zone dedicated to +only Users in a given domain can create guests in a zone dedicated to that domain. There are several types of dedication available: - Explicit dedication. A zone, pod, cluster, or host is dedicated to an - account or domain by the root administrator during initial deployment + Account or domain by the root administrator during initial deployment and configuration. - Strict implicit dedication. A host will not be shared across multiple - accounts. For example, strict implicit dedication is useful for + Accounts. For example, strict implicit dedication is useful for deployment of certain types of applications, such as desktops, where - no host can be shared between different accounts without violating + no host can be shared between different Accounts without violating the desktop software's terms of license. -- Preferred implicit dedication. The VM will be deployed in dedicated - infrastructure if possible. Otherwise, the VM can be deployed in +- Preferred implicit dedication. The Instance will be deployed in dedicated + infrastructure if possible. Otherwise, the Instance can be deployed in shared infrastructure. @@ -257,7 +275,7 @@ How to Dedicate a Zone, Cluster, Pod, or Host to an Account or Domain For explicit dedication: When deploying a new zone, pod, cluster, or host, the root administrator can click the Dedicated checkbox, then -choose a domain or account to own the resource. +choose a domain or Account to own the resource. To explicitly dedicate an existing zone, pod, cluster, or host: log in as the root admin, find the resource in the UI, and click the Dedicate @@ -268,7 +286,7 @@ offering and in the Deployment Planner field, chooses ImplicitDedicationPlanner. Then in Planner Mode, the administrator specifies either Strict or Preferred, depending on whether it is permissible to allow some use of shared resources when dedicated -resources are not available. Whenever a user creates a VM based on this +resources are not available. Whenever a User creates an Instance based on this service offering, it is allocated on one of the dedicated hosts. @@ -277,39 +295,39 @@ How to Use Dedicated Hosts To use an explicitly dedicated host, use the explicit-dedicated type of affinity group (see `“Affinity Groups” `_). -For example, when creating a new VM, an -end user can choose to place it on dedicated infrastructure. This +For example, when creating a new Instance, an +end User can choose to place it on dedicated infrastructure. This operation will succeed only if some infrastructure has already been -assigned as dedicated to the user's account or domain. +assigned as dedicated to the User's Account or domain. Behavior of Dedicated Hosts, Clusters, Pods, and Zones ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The administrator can live migrate VMs away from dedicated hosts if +The administrator can live migrate Instances away from dedicated hosts if desired, whether the destination is a host reserved for a different -account/domain or a host that is shared (not dedicated to any particular -account or domain). CloudStack will generate an alert, but the operation +Account/domain or a host that is shared (not dedicated to any particular +Account or domain). CloudStack will generate an alert, but the operation is allowed. Dedicated hosts can be used in conjunction with host tags. If both a -host tag and dedication are requested, the VM will be placed only on a +host tag and dedication are requested, the Instance will be placed only on a host that meets both requirements. If there is no dedicated resource -available to that user that also has the host tag requested by the user, -then the VM will not deploy. +available to that User that also has the host tag requested by the User, +then the Instance will not deploy. -If you delete an account or domain, any hosts, clusters, pods, and zones +If you delete an Account or domain, any hosts, clusters, pods, and zones that were dedicated to it are freed up. They will now be available to be -shared by any account or domain, or the administrator may choose to -re-dedicate them to a different account or domain. +shared by any Account or domain, or the administrator may choose to +re-dedicate them to a different Account or domain. System VMs and virtual routers affect the behavior of host dedication. System VMs and virtual routers are owned by the CloudStack system -account, and they can be deployed on any host. They do not adhere to -explicit dedication. The presence of system vms and virtual routers on a +Account, and they can be deployed on any host. They do not adhere to +explicit dedication. The presence of system VMs and virtual routers on a host makes it unsuitable for strict implicit dedication. The host can not be used for strict implicit dedication, because the host already has -VMs of a specific account (the default system account). However, a host +VMs of a specific Account (the default system Account). However, a host with system VMs or virtual routers can be used for preferred implicit dedication. @@ -320,74 +338,74 @@ Using an LDAP Server for User Authentication You can use an external LDAP server such as Microsoft Active Directory or ApacheDS to authenticate CloudStack end-users. CloudStack will search the external LDAP directory tree starting at a specified base directory -and gets user info such as first name, last name, email and username. +and gets User info such as first name, last name, email and username. Starting with CloudStack 4.11, an LDAP connection per domain can be -defined. In this domain autosync per account can be configured, -keeping the users in the domain up to date with their group membership +defined. In this domain autosync per Account can be configured, +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 + 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 +There are now three ways to link LDAP Users to CloudStack Users. These three ways where developed as extensions on top of each other. To authenticate, in all three cases username and password entered by -the user are used. +the User are used. -#. **manual import**. A user is explicitely mapped to a domain/account - and created as a user in that account. +#. **manual import**. A User is explicitly mapped to a domain/Account + and created as a User in that Account. - #. CloudStack does a search for a user with the given username. + #. CloudStack does a search for a User with the given username. - #. If it exists, it checks if the user is enabled. + #. If it exists, it checks if the User is enabled. - #. If the user is enabled, CloudStack searches for it in LDAP + #. If the User is enabled, CloudStack searches for it in LDAP by the configured ``ldap.username.attribute``. - #. If the LDAP user is found, CloudStack does a bind request - with the returned principal for that LDAP user and the + #. If the LDAP User is found, CloudStack does a bind request + with the returned principal for that LDAP User and the entered password. #. 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, an account in the - same name as the user is automatically created 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, #. CloudStack searches for it in LDAP by the configured ``ldap.username.attribute``. - #. If an LDAP user is found, CloudStack does a bind - request with the returned principal for that LDAP user and + #. If an LDAP User is found, CloudStack does a bind + request with the returned principal for that LDAP User and the entered password. #. If LDAP authentication checks out, CloudStack checks if the - authenticated user exists in the domain it is trying to log + authenticated User exists in the domain it is trying to log on to. - #. If the user exists in CloudStack, it is ensured to be enabled. + #. If the User exists in CloudStack, it is ensured to be enabled. - #. If it doesn't exist it is created in a new account with - the username as names for both account and user. + #. If it doesn't exist it is created in a new Account with + the username as names for both Account and User. - #. In case authentication fails the user will be disabled in + #. In case authentication fails the User will be disabled in cloudstack after the configured ``incorrect.login.attempts.allowed`` number of attempts. #. **autosync**. A domain is configured to use a LDAP server and in this - domain a number of accounts are 'mapped' against LDAP groups. Any - user that is in one of these configured accounts will be checked against the + domain a number of Accounts are 'mapped' against LDAP groups. Any + User that is in one of these configured Accounts will be checked against the current state of LDAP and if they exist they will be asserted to be - in the right account according to their LDAP group. If they do not + in the right Account according to their LDAP group. If they do not exist in LDAP they will be disabled in CloudStack. #. If the domain is configured to be used by LDAP, @@ -395,21 +413,21 @@ the user are used. #. CloudStack searches for it in LDAP by the configured ``ldap.username.attribute``. - #. If an LDAP user is found, it is checked for - memberships of mapped account, i.e. accounts for which LDAP + #. If an LDAP User is found, it is checked for + memberships of mapped Account, i.e. Accounts for which LDAP groups are configured. - #. If the LDAP user has 0, 2 or more memberships the account + #. If the LDAP User has 0, 2 or more memberships the Account is disabled and authentication fails. #. CloudStack then does a bind request with the returned - principal for that LDAP user and the entered password. + principal for that LDAP User and the entered password. - #. If no CloudStack user exists it is created in the - appropriate account. + #. 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. + #. 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 @@ -424,8 +442,8 @@ replicas. If one fails, the next one is used. 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. +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 @@ -438,7 +456,7 @@ LDAP. For instance 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 +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. @@ -448,7 +466,7 @@ to be applied through the API call described above. [ -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 + # 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" @@ -465,37 +483,77 @@ to be applied through the API call described above. 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** - -- ``ldap.bind.principal``, ``ldap.bind.password``: DN and password for a user - who can list all the users in the above basedn. Ex: - **CN=Administrator, OU=APAC, DC=company, DC=com** +configuration items can be configured on a Global or on a per Domain level (the default values are for +OpenLDAP) + +.. list-table:: LDAP Settings + :header-rows: 1 + + * - Setting + - OpenLDAP + - Active Directory + - Description + * - ``ldap.basedn`` + - `Ex: OU=APAC, DC=company, DC=com` + - `Ex: DC=company, DC=com` + - Sets the basedn for LDAP. + * - ``ldap.search.group.principle`` + - `Ex: CN=ACSGroup, DC=company, DC=com` + - `Ex: CN=ACSGroup, CN=Users, DC=company, DC=com` + - (optional) if set only Users from this group are listed. + * - ``ldap.bind.principal`` + - `Ex: CN=ACSServiceAccount, OU=APAC, DC=company, DC=com` + - `Ex: CN=ACSServiceAccount, CN=Users, DC=company, DC=com` + - Service account that can list all the Users in the above basedn. Avoid using privileged account such as Administrator. + * - ``ldap.bind.password`` + - `******************` + - `******************` + - Password for a DN User. Is entered in plain text but gets stored encrypted. + * - ``ldap.user.object`` + - `interorgperson` + - `user` + - Object type of Users within LDAP. + * - ``ldap.email.attribute`` + - `mail` + - `mail` + - Email attribute within ldap for a User. + * - ``ldap.firstname.attribute`` + - `givenname` + - `givenname` + - firstname attribute within ldap for a User. + * - ``ldap.lastname.attribute`` + - `sn` + - `sn` + - lastname attribute within ldap for a User. + * - ``ldap.group.object`` + - `groupOfUniqueNames` + - `groupOfUniqueNames` + - Object type of groups within LDAP. + * - ``ldap.group.user.uniquemember`` + - `uniquemember` + - `uniquemember` + - Attribute for uniquemembers within a group. + + .. note:: ``ldap.search.group.principle`` is required when using ``linkaccounttoldap``. + +Once configured, on Add Account page, you will see an "Add LDAP Account" button which opens a dialog and the selected Users can be imported. -- ``ldap.user.object``: object type of users within LDAP. Defaults value is - **user** for AD and **interorgperson** for openldap. - -- ``ldap.email.attribute``: email attribute within ldap for a user. Default - value for AD and openldap is **mail**. +.. figure:: /_static/images/CloudStack-ldap-screen1.png + :align: center -- ``ldap.firstname.attribute``: firstname attribute within ldap for a user. - Default value for AD and openldap is **givenname**. -- ``ldap.lastname.attribute``: lastname attribute within ldap for a user. - Default value for AD and openldap is **sn**. +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 -- ``ldap.username.attribute``: username attribute for a user within LDAP. - Default value is **SAMAccountName** for AD and **uid** for openldap. +Once LDAP is enabled, the Users will not be allowed to changed password +directly in CloudStack. -Restricting LDAP users to a group: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``ldap.search.group.principle``: this is optional and if set only users from - this group are listed. + .. note:: this is required when using ``linkaccounttoldap``. LDAP SSL: ~~~~~~~~~ @@ -508,47 +566,23 @@ You will need to know the path to the keystore and the password. - ``ldap.truststore.password`` : truststore password -LDAP groups: -~~~~~~~~~~~~ - -- ``ldap.group.object``: object type of groups within LDAP. Default value is - group for AD and **groupOfUniqueNames** for openldap. - -- ``ldap.group.user.uniquemember``: attribute for uniquemembers within a group. - Default value is **member** for AD and **uniquemember** for openldap. - -Once configured, on Add Account page, you will see an "Add LDAP Account" button -which opens a dialog and the selected users can be imported. - -.. figure:: /_static/images/CloudStack-ldap-screen1.png - :align: center - - -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 ---------------------------------------------------------- -You can use a SAML 2.0 Identity Provider with CloudStack for user +You can use a SAML 2.0 Identity Provider with CloudStack for User authentication. This will require enabling the SAML 2.0 service provider plugin in CloudStack. To do that first, enable the SAML plugin by setting ``saml2.enabled`` to ``true`` and restart management server. -Starting 4.5.2, the SAML plugin uses an authorization workflow where users should -be authorized by an admin using ``authorizeSamlSso`` API before those users can +Starting 4.5.2, the SAML plugin uses an authorization workflow where Users should +be authorized by an admin using ``authorizeSamlSso`` API before those Users can use Single Sign On against a specific IDP. This can be done by ticking the enable -SAML Single Sign On checkbox and selecting a IDP when adding or importing users. -For existing users, admin can go to the user's page and click on configure -SAML SSO option to enable/disable SSO for a user and select a Identity Provider. -A user can be authorized to authenticate against only one IDP. +SAML Single Sign On checkbox and selecting a IDP when adding or importing Users. +For existing Users, admin can go to the User's page and click on configure +SAML SSO option to enable/disable SSO for a User and select a Identity Provider. +A User can be authorized to authenticate against only one IDP. The CloudStack service provider metadata is accessible using the ``getSPMetadata`` API command, or from the URL @@ -556,25 +590,25 @@ http://acs-server:8080/client/api?command=getSPMetadata where acs-server is the domain name or IP address of the management server. The IDP administrator can get the SP metadata from CloudStack and add it to their IDP server. -To start a SAML 2.0 Single Sign-On authentication, on the login page users need to +To start a SAML 2.0 Single Sign-On authentication, on the login page Users need to select the Identity Provider or Institution/Department they can authenticate with and click on Login button. This action call the ``samlsso`` API command which -will redirect the user to the Identity Provider's login page. Upon successful -authentication, the IdP will redirect the user to CloudStack. In case a user has -multiple user accounts with the same username (across domains) for the same -authorized IDP, that user would need to specify domainpath after selecting their -IDP server from the dropdown list. By default, users don't need to specify any -domain path. After a user is successfully authenticated by an IDP server, the SAML -authentication plugin finds user accounts whose username match the username +will redirect the User to the Identity Provider's login page. Upon successful +authentication, the IdP will redirect the User to CloudStack. In case a User has +multiple User Accounts with the same username (across domains) for the same +authorized IDP, that User would need to specify domainpath after selecting their +IDP server from the dropdown list. By default, Users don't need to specify any +domain path. After a User is successfully authenticated by an IDP server, the SAML +authentication plugin finds User Accounts whose username match the username attribute value returned by the SAML authentication response; it fails -only when it finds that there are multiple user accounts with the same user name +only when it finds that there are multiple User Accounts with the same User name for the specific IDP otherwise the unique useraccount is allowed to proceed and -the user is logged into their account. +the User is logged into their Account. Limitations: -- The plugin uses a user attribute returned by the IDP server in the SAML response - to find and map the authorized user in CloudStack. The default attribute is `uid`. +- The plugin uses a User attribute returned by the IDP server in the SAML response + to find and map the authorized User in CloudStack. The default attribute is `uid`. - The SAML authentication plugin supports HTTP-Redirect and HTTP-Post bindings. @@ -611,3 +645,451 @@ The following global configuration should be configured: - ``saml2.timeout``: SAML2 IDP Metadata refresh interval in seconds, minimum value is set to 300. Default is 1800 +Using OAuth2 Authentication For Users +------------------------------------------ + +OAuth2, the industry-standard authorization or authentication framework, simplifies the process of +granting access to resources. CloudStack supports OAuth2 authentication wherein users can login into +CloudStack without using username and password. CloudStack currently supports Google and GitHub providers. +Other OAuth2 providers can be easily integrated with CloudStack using its plugin framework. + +For admins, the following are the settings available at global level to configure OAuth2. + +.. cssclass:: table-striped table-bordered table-hover + +================================================ ================ =================================================================== +Global setting Default values Description +================================================ ================ =================================================================== +oauth2.enabled false Indicates whether OAuth plugin is enabled or not +oauth2.plugins google,github List of OAuth plugins +oauth2.plugins.exclude List of OAuth plugins which are excluded +================================================ ================ =================================================================== + +The login page when the OAuth2 is enabled and corresponding providers are configured. + +.. image:: /_static/images/oauth-login.png + :width: 400px + :align: center + :alt: Login page with OAuth logins + +"OAuth configuration" sub-section is added under "Configuration" where admins can register the corresponding +OAuth providers. + +.. image:: /_static/images/oauth-sub-section.png + :width: 120px + :align: center + :alt: OAuth configuration section + +.. image:: /_static/images/oauth-configuration-details.png + :width: 400px + :align: center + :alt: OAuth configuration details + +To register the OAuth provider client ID, redirect URI, secret key have to provided. +OAuth 2.0 has to be first configured in the corresponding provider to obtain the client ID, redirect URI, secret Key. + +For Google, please follow the instructions mentioned here `"Setting up OAuth 2.0 in Google" `_. +For GitHub, please follow the instructions mentioned here `"Setting up OAuth 2.0 in GitHub" `_. + +In any OAuth 2.0 configuration admin has to use the redirect URI "http://:/#/verifyOauth" + +.. Note:: [Google OAuth 2.0 redirect URI] : + Google OAuth 2.0 configuration won't accept '#' in the URI, please use "http://:/?verifyOauth" + Google does not accept direct IP address in the redirect URI, it must be a domain. As a workaround one can add the management + server IP to host table in the local system and assign a domain, something like "management.cloud". In that redirect URI looks like + "http://management.cloud:8080/?verifyOauth" + +Following are the details needs to be provided to register the OAuth provider, this is to call the API "registerOauthProvider" + + - **Provider**: Name of the provider from the list of OAuth providers supported in CloudStack + + - **Description**: A short description for the provider + + - **Provider Client ID**: Client ID pre-registered in the specific OAuth provider + + - **Redirect URI**: Redirect URI pre-registered in the specific OAuth provider + + - **Secret Key**: Secret Key pre-registered in the specific OAuth provider + +.. image:: /_static/images/oauth-provider-registration.png + :width: 400px + :align: center + :alt: OAuth provider registration + +Cloudmonkey API call looks like + + - register oauthprovider provider=google description="Google Provider" + clientid="http://345798102268-3kp6qd6c16v6b9av2tmvqagj40na30l4.apps.googleusercontent.com" + redirecturi="http://local.cloud:8080/?verifyOauth" secretkey="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" + +Email address is the key to identify the user in CloudStack. In case if user belongs to any specific domain, domain name +has to be provided in the login form and then click on OAuth login. + +.. image:: /_static/images/user-domain-login.png + :width: 400px + :align: center + :alt: Login page for user under specific domain + +Using Two Factor Authentication For Users +------------------------------------------ + +CloudStack supports two factor authentication wherein Users need to provide a 2FA code after the +regular login using username and password. CloudStack currently supports Google Authenticator or +other TOTP authenticators and static PIN as the 2FA providers. Other 2FA providers can be easily +integrated with CloudStack using its plugin model. + +.. Note:: 2FA is applicable to authentication mechanisms in CloudStack using username/password, + LDAP, SAML. While using apikey/secretkey 2FA checks will be bypassed. + +For admins, the following are the settings available at global and domain level to configure 2FA. + +.. cssclass:: table-striped table-bordered table-hover + +================================================ ================ =================================================================== +Global setting Default values Description +================================================ ================ =================================================================== +enable.user.2fa false Determines whether 2FA is enabled or not +mandate.user.2fa false Determines whether to make the 2FA mandatory or not for the Users +user.2fa.default.provider totp The default User 2FA provider plugin. Eg. totp, staticpin +================================================ ================ =================================================================== + +If 2FA is configured for the User, the 2FA verification page looks like below after the login. + +The verification page when the User configures 2FA using Google or other TOTP Authenticators. + +.. image:: /_static/images/verify-2fa-totp.png + :width: 400px + :align: center + :alt: Verify 2FA page using TOTP + +The verification page when the User configures 2FA using Static PIN. + +.. image:: /_static/images/verify-2fa-staticpin.png + :width: 400px + :align: center + :alt: Verify 2FA page using static PIN + +Users can configure 2FA in CloudStack using the action button in User form. + +.. image:: /_static/images/configure-2fa-action-button.png + :width: 400px + :align: center + :alt: Configure 2FA action button + + +In the 2FA setup form, the User needs to select one of the providers. CloudStack currently supports +Google Authenticator or other TOTP Authenticators and static PIN as the 2FA providers. + +When the Google Authenticator or other TOTP 2FA provider is selected, the User must setup the Account in +the respective application in their device by either scanning the QR code or using the setup key provided +by CloudStack. Once this is set up in the authenticator application, the User must always use the provided +2FA codes to log in. + +.. image:: /_static/images/configure-google-2fa-form.png + :width: 400px + :align: center + :alt: Configure Google 2FA form + + +When the static PIN 2FA provider is selected, the User must use the static PIN as the code to verify 2FA +with CloudStack. The User must input this static PIN as a 2FA code every time they need to login. + +.. image:: /_static/images/configure-staticpin-2fa-form.png + :width: 400px + :align: center + :alt: Configure static PIN 2FA form + +The admin has the capability to mandate 2FA for Users via the setting ``mandate.user.2fa``. +In this case the User must configure 2FA during their first login into CloudStack. + +The User's first login page to configure 2FA looks like the below. + +.. image:: /_static/images/configure-2fa-at-login-page.png + :width: 400px + :align: center + :alt: Configure 2FA at login page + + +For the existing Users, the admin can mandate 2FA using the 'updateUser' API with the parameter 'mandate2FA'. + +The admin can also disable 2FA for a User using the action button as shown below. + +.. image:: /_static/images/disable-2fa.png + :width: 400px + :align: center + :alt: Disable 2FA action button + +.. Note:: [2FA Recovery process] : + If the User loses the authenticator application or forgets the static PIN, then the User must + contact admin to disable 2FA. + If the admin themself loses the authenticator application or forgets the static PIN, then the admin + will have to either use apikey to disable 2FA using the API setupUserTwoFactorAuthentication with + enable flag to false or to do the database changes in 'user' table by clearing the columns + 'is_user_2fa_enabled', 'key_for_2fa', 'user_2fa_provider' for the specific entry. + +Password Recovery for Users (Forgot Password) +--------------------------------------------- + +CloudStack supports password recovery using email. To enable this feature, +set global setting `user.password.reset.enabled` to `true`. The following +global settings are available to configure SMTP for password recovery. + + +.. list-table:: Password Recovery Global Settings + :header-rows: 1 + + * - Global setting + - Default + - Description + * - ``user.password.reset.enabled`` + - `false` + - Determines whether password recovery via email is enabled or not. + * - ``user.password.reset.ttl`` + - `30` + - TTL in minutes for the token generated to reset the ACS user's password. + * - ``user.password.reset.email.sender`` + - `null` + - Sender for emails sent to the user to reset ACS user's password + * - ``user.password.reset.smtp.host`` + - `null` + - Host for SMTP server + * - ``user.password.reset.smtp.port`` + - `25` + - Port for SMTP server + * - ``user.password.reset.smtp.useAuth`` + - `false` + - Use auth in the SMTP server + * - ``user.password.reset.smtp.username`` + - `null` + - Username for SMTP server + * - ``user.password.reset.smtp.password`` + - `null` + - Password for SMTP Server + * - ``user.password.reset.mail.template`` + - `Hello {{username}}!` + + `You have requested to reset your password. Please click the following link to reset your password:`` + + `http://{{{resetLink}}}` + + `If you did not request a password reset, please ignore this email.` + + + `Regards,` + + `The CloudStack Team` + - Template of mail sent to the user to reset ACS user's password. This uses + mustache template engine. Available variables are: `username`, + `firstName`, `lastName`, `resetLink`, `token`. + + +Once the global settings are configured, follow the below steps to reset the +password for a user: + +#. Open the "Forgot Password" link on the login page. + + .. figure:: /_static/images/default-login.png + :align: center + +#. Enter your username and domain name and click on "Submit". + + .. figure:: /_static/images/forgot-password.png + :align: center + +#. An email will be sent to the User with a link to reset the password. + +#. Open the link in the email and set the new password. + + .. figure:: /_static/images/reset-password.png + :align: center + +Add Users +------------ +CloudStack allows administrators to create :ref:`users` within an Account. +Users represent individual identities that can access CloudStack +resources based on their assigned roles and permissions. + +Who can add Users +~~~~~~~~~~~~~~~~~~ + +The following administrators can create Users: + +- Root Administrators – across all domains and accounts +- Domain Administrators – within their domain hierarchy + +**UI Flow:** + +#. Navigate to **Accounts → Users**. +#. Click **Add User**. +#. Fill in the User details, including the initial password. +#. (Optional) Enable **User must change password at next login**. +#. Add the User. + +.. figure:: /_static/images/add-user-popup.png + :align: center + :alt: Add user by administrator + :width: 400px + +If password change is enforced during User creation, the User is prompted to +change the password on first login. +See :ref:`user-login-flow-enforced-password-change`. + + +Password Change for Users +------------------------- +CloudStack allows User passwords to be changed either by the User +themselves or by an administrator. Password changes may be performed +voluntarily or as part of an administrative action. + +User-initiated password changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Users can change their own password at any time after successfully +logging in to the CloudStack UI. + +**UI Flow:** + +#. Log in to the CloudStack UI. +#. Click the User profile menu. +#. Select **Change Password**. +#. Enter the current password. +#. Enter and confirm the new password. +#. Submit the change. + +.. figure:: /_static/images/user-change-password-popup.png + :align: center + :alt: User changing their own password + :width: 400px + +Administrator-initiated password changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Root and Domain Admins can change User's password when required, for example +during account recovery or administrative maintenance. + +**UI Flow:** + +#. Navigate to **Accounts → Users**. +#. Open the required User details page. +#. Select **Change Password**. +#. (Optional) Enable **User must change password at next login**. +#. Change the password. + +.. figure:: /_static/images/admin-change-password-popup.png + :align: center + :alt: Change user password by administrator + :width: 400px + +When password change is selected, the User must change the temporary password on the +next login. See :ref:`user-login-flow-enforced-password-change`. + + +Force Password Reset for Users (Quick Action) +----------------------------------------------- +CloudStack allows administrators to enforce a password change +**without modifying the current password**. + +**UI Flow:** + +#. Navigate to **Accounts → Users**. +#. Open the required User details page. +#. Click **Force password reset** from the actions menu. +#. Confirm the action. + +.. figure:: /_static/images/force-password-reset-quick-action.png + :align: center + :alt: Force password reset using quick action + +.. raw:: html + +
+ +.. _user-login-flow-enforced-password-change: +User login flow for enforced password change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When password change is enforced, the User login flow is as follows: + +#. The User enters username, domain, and password. +#. Authentication succeeds. +#. The User is redirected to the **Change Password** page. +#. The User must set a new password that complies with configured + password policies. +#. Until the password is changed, no other UI actions or API operations are permitted. +#. Upon successful password update, normal access is granted. + +.. figure:: /_static/images/force-password-change-login.png + :align: center + :alt: User prompted to change password after login + :width: 400px + +Using API Key and Secret Key based Authentication +------------------------------------------------- +Users can generate API key and Secret key to directly access CloudStack APIs. +This authentication method is used for programmatically calling CloudStack APIs and thus helps in automation. +The API key uniquely identifies the Account, while the Secret key is used to generate a secure signature. +When making an API call, the API key and signature are included along with the command and other parameters, +and sent to the CloudStack API endpoint. For detailed information, refer to the CloudStack's Programmer Guide. + +Disabling Api Key and Secret Key based Access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Root Administrators may choose to Disable Api key based access for certain Users, Accounts or Domains. +Or the Administrator may choose to Disable Api Key based access globally and allow only for certain users. +This could be particularly useful in cases where external authorization mechanisms like LDAP, SAML or OAuth2 are used, +as then Api key based authorization is the only means for automation. +This gives control to the Admin over who is allowed to run automation. + +Api key based access is enabled by default but it can be disabled (or enabled) at different granularities: + +1. Users + +Setting for a User can be changed through the Api Key Access field in the Edit User form, visible only to the Root Administrator. +Three values are possible: Disable, Enable and Inherit. Inherit means that the User will inherit whatever value is set for the Account. + + .. figure:: /_static/images/edit-user-api-key-access.png + :align: center + +Admins can also search for Users having the required Api key access value using the User list view search filter. + + .. figure:: /_static/images/filter-user-api-key-access.png + :align: center + +2. Accounts + +Similar to Users, Api Key Access field is present in the Edit Account Form and the Account list view search filter, only for the Root Administrator. +If the value is set to Inherit, it means that Account will inherit whatever value is set for the Domain. + +3. Domains + +Api Key Access at Domain level is controlled by the Domain level setting "api.key.access". If the Domain level +configuration is not set, then similar to other configurations it will consult the global value. + +4. Global + +The global value of the configuration setting "api.key.access" is set to 'True' by default. So Api Key Access at +all levels is enabled by default. If the global value is changed to 'False' without setting any of the lower levels, +then Api Key Access will be disabled for all Users. + +Order of Precedence +^^^^^^^^^^^^^^^^^^^ +The local value always takes precedence over the global value. So if Api key access is disabled for a User but +enabled for an Account, the User authorisation will still fail. Only if the User's Api key access is set to +'Inherit', the Account's Api Key Access value is considered. +Similarly if Account's Api Key Access is set to 'Inherit', only then the Domain level setting is considered, +And only if the Domain level configuration is not set, the Global configuration is considered. + +Examples +^^^^^^^^ + +#. Disallow Api key access for all Accounts and Users in a Domain. + + #. Leave all User and Account level Api Key Access values to the default 'Inherit'. + #. Set the Domain level setting "api.key.access" to False only for the required domain. + +#. Disallow Api key access for some Users, but allowed globally. + + #. Set the User level permission to ‘Disabled’ only for the required Users. + #. All upper level permissions should either be Inherit or Enabled. + +#. Allow Api key access to some Users, but disallowed globally. + + #. Set User level permission to ‘Enabled’ only for the required Users. + #. All upper level permissions should either be Inherit or Disabled. diff --git a/source/adminguide/administration.rst b/source/adminguide/administration.rst index 4baa17ffa6..908d07cfb3 100644 --- a/source/adminguide/administration.rst +++ b/source/adminguide/administration.rst @@ -18,14 +18,14 @@ User Services ============= In addition to the physical and logical infrastructure of your cloud and -the CloudStack software and servers, you also need a layer of user +the CloudStack software and servers, you also need a layer of User services so that people can actually make use of the cloud. This means -not just a user UI, but a set of options and resources that users can -choose from, such as templates for creating virtual machines, disk +not just a User UI, but a set of options and resources that Users can +choose from, such as Templates for creating Instances, disk storage, and more. If you are running a commercial service, you will be -keeping track of what services and resources users are consuming and +keeping track of what services and resources Users are consuming and charging them for that usage. Even if you do not charge anything for -people to use your cloud – say, if the users are strictly internal to +people to use your cloud – say, if the Users are strictly internal to your organization, or just friends who are sharing your cloud – you can still keep track of what services they use and how much of them. @@ -33,9 +33,9 @@ still keep track of what services they use and how much of them. Service Offerings, Disk Offerings, Network Offerings, and Templates ------------------------------------------------------------------- -A user creating a new instance can make a variety of choices about its +A User creating a new Instance can make a variety of choices about its characteristics and capabilities. CloudStack provides several ways to -present users with choices when creating a new instance: +present Users with choices when creating a new Instance: - Service Offerings, defined by the CloudStack administrator, provide a choice of CPU speed, number of CPUs, RAM size, tags on the root disk, @@ -46,16 +46,16 @@ present users with choices when creating a new instance: storage. See Creating a New Disk Offering. - Network Offerings, defined by the CloudStack administrator, describe - the feature set that is available to end users from the virtual + the feature set that is available to end Users from the virtual router or external networking devices on a given guest network. See Network Offerings. - Templates, defined by the CloudStack administrator or by any - CloudStack user, are the base OS images that the user can choose from - when creating a new instance. For example, CloudStack includes CentOS - as a template. See Working with Templates. + CloudStack User, are the base OS images that the User can choose from + when creating a new Instance. For example, CloudStack includes CentOS + as a Template. See Working with Templates. -In addition to these choices that are provided for users, there is +In addition to these choices that are provided for Users, there is another type of service offering which is available only to the CloudStack root administrator, and is used for configuring virtual infrastructure resources. For more information, see Upgrading a Virtual diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index e4e4e445bf..d0a269b30b 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -12,7 +12,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + The CloudStack API is a low level API that has been used to implement the CloudStack web UIs. It is also a good basis for implementing other @@ -46,82 +46,85 @@ Authentication. User Data and Meta Data ~~~~~~~~~~~~~~~~~~~~~~~ -The user-data service on a Shared or Isolated Network can be provided through the +The User Data service on a Shared or Isolated Network can be provided through the Virtual Router or through an attached iso called the Config drive. User Data and Meta Data Via Virtual Router ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack provides API access to attach up to 32KB of user data to a -deployed VM. Deployed VMs also have access to instance metadata via the +CloudStack provides API access to attach up to 32KB of User Data to a +deployed Instance. Deployed Instances also have access to metadata via the virtual router. -User data can be accessed once the IP address of the virtual router is +User Data can be accessed once the IP address of the virtual router is known. Once the IP address is known, use the following steps to access -the user data: +the User Data: #. Run the following command to find the virtual router. .. code:: bash + # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -1 -#. Access user data by running the following command using the result of +#. Access User Data by running the following command using the result of the above command .. code:: bash + # curl http://10.1.1.1/latest/user-data + Meta Data can be accessed similarly, using a URL of the form http://10.1.1.1/latest/meta-data/{metadata type}. (For backwards compatibility, the previous URL http://10.1.1.1/latest/{metadata type} is also supported.) For metadata type, use one of the following: -- service-offering. A description of the VMs service offering +- service-offering. A description of the Instance service offering - availability-zone. The Zone name -- local-ipv4. The guest IP of the VM +- local-ipv4. The guest IP of the Instance -- local-hostname. The hostname of the VM +- local-hostname. The hostname of the Instance - public-ipv4. The first public IP for the router. (E.g. the first IP of eth2) - public-hostname. This is the same as public-ipv4 -- instance-id. The instance name of the VM +- instance-id. The Instance name User Data and Meta Data via Config Drive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Config drive is an ISO file that is mounted as a cd-rom on a user VM and -contains the user VM related userdata, metadata (incl. ssh-keys) and +Config drive is an ISO file that is mounted as a cd-rom on a user Instance and +contains related User Data, metadata (incl. ssh-keys) and password files. Enable config drive ~~~~~~~~~~~~~~~~~~~ -To use the config drive the network offering must have the “ConfigDrive” -provider selected for the userdata service. +To use the config drive the Network offering must have the “ConfigDrive” +provider selected for the User Data service. -If the networkoffering uses ConfigDrive for userdata and the template is -password enabled, the password string for the VM is placed in the +If the networkoffering uses ConfigDrive for User Data and the Template is +password enabled, the password string for the Instance is placed in the vm_password.txt file and it is included in the ISO. ConfigDrive availability ~~~~~~~~~~~~~~~~~~~~~~~~ -At VM start the config drive ISO is attached on the 2nd cd/dvd drive of the -user instance, such that any other ISO image (e.g. boot image or vmware tools) +At Instance start the config drive ISO is attached on the 2nd cd/dvd drive of the +user Instance, such that any other ISO image (e.g. boot image or vmware tools) is mounted on 1st cd/dvd drive. This means existing functionality of supporting 1 cd rom drive is still available. -At password reset or update of user data, the Config Drive ISO +At password reset or update of User Data, the Config Drive ISO will be rebuilt. The existing ISO is mounted on a temporary directory, -password, userdata or ssh-keys are updated and a new ISO is built from the +password, User Data or ssh-keys are updated and a new ISO is built from the updated directory structure. -In case of a password reset, the new password will be picked-up at VM start. -To access the updated userdata, the user needs to remount the config drive ISO. +In case of a password reset, the new password will be picked-up at Instance start. +To access the updated User Data, the user needs to remount the config drive ISO. -When a VM is stopped, the ConfigDrive network element will trigger the +When an Instance is stopped, the ConfigDrive network element will trigger the Secondary Storage VM to remove the ISO from the secondary storage. If the config drive is stored on primary storage, the network element will trigger the host to remove the ISO. @@ -133,7 +136,7 @@ supported with use of the KVM Hypervisor. Supporting ConfigDrive ~~~~~~~~~~~~~~~~~~~~~~ -Extra data is added to the VM profile to enable the creation of the config drive: +Extra data is added to the Instance profile to enable the creation of the config drive: VMdata - a list of String arrays representing [“directory”, “filename”, “content”] on the ConfigDrive device. @@ -159,7 +162,7 @@ VMdata - a list of String arrays representing [“directory”, “filename”, - vm_password.txt - - vm_password_md5checksum (for windows VM’s) + - vm_password_md5checksum (for windows Instances) - /openstack/version/: @@ -169,7 +172,7 @@ VMdata - a list of String arrays representing [“directory”, “filename”, - meta_data.json - - Network_data.json + - network_data.json - label, which is configurable in global settings: @@ -177,6 +180,29 @@ VMdata - a list of String arrays representing [“directory”, “filename”, - default: config-2 +Virtual machine password via ConfigDrive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ConfigDrive metadata provider delivers the virtual machine password simultaneously in two variants, leaving which one to use to the user discretion: + +1. As the ``/cloudstack/password/vm_password.txt`` file. + +This file is intended to be used by an external script that runs inside the virtual machine every boot, and changes the password if needed. +The init-script that implements this functionality can be found in the `Cloudstack source `_. + +.. note:: + The ``vm_password.txt`` file is not compatible with cloud-init password module, so the cloud-init will ignore it. + It is up to Cloudstack administrator to include the script processing it in the virtual machines and/or their templates. + +2. As the ``/openstack/latest/vendor_data.json``. +This is a standard password location supported by cloud-init's both ConfigDrive datasource and the password module. +Therefore, this variant allows using cloud-init as the only tool for provisioning a virtual machine, without using external scripts. + +.. warning:: + Cloud-init password module is designed to only perform the initial virtual machine password setup. + It will ignore the changes in ``vendor_data.json`` after the first run. Therefore, resetting the virtual machine password from Cloudstack will not work with this variant. + + For more detailed information about the Config Drive implementation refer to the `Wiki Article `_ diff --git a/source/adminguide/arch_types.rst b/source/adminguide/arch_types.rst new file mode 100644 index 0000000000..eea29adec8 --- /dev/null +++ b/source/adminguide/arch_types.rst @@ -0,0 +1,30 @@ +.. 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. + + +Hosts/Cluster Arch Types Allocation +=================================== + +Since CloudStack 4.20.0, it is possible to add AMD 64 bits and ARM 64 bits clusters (and hosts). A single zone can contain clusters (and hosts) of different arch types (multi-arch zones). + +When a multi-arch zone is selected for VM deployment, CloudStack allows the users to filter the templates/ISOs by their arch type. + +|deploy-vm-arch-types.png| + +Once a template/ISO is selected, only the clusters (and hosts) matching the arch type will be considered for the VM allocation + +.. |deploy-vm-arch-types.png| image:: /_static/images/deploy-vm-arch-types.png + :alt: Filtering templates and ISOs by arch types + diff --git a/source/adminguide/autoscale_with_virtual_router.rst b/source/adminguide/autoscale_with_virtual_router.rst new file mode 100644 index 0000000000..4370fec387 --- /dev/null +++ b/source/adminguide/autoscale_with_virtual_router.rst @@ -0,0 +1,403 @@ +.. 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. + + +Configuring AutoScale with the CloudStack Virtual Router +============================================= + + +What is AutoScaling? +-------------------- + +AutoScaling allows you to scale your back-end services or application Instances up +or down seamlessly and automatically according to the conditions you define. +With AutoScaling enabled, you can ensure that the number of Instances you are using +seamlessly scale up when demand increases, and automatically decreases when +demand subsides. Thus it helps you save compute costs by terminating underused +Instances automatically and launching new ones when you need them, without the need +for manual intervention. + + +Hypervisor support +------------------ + +At that time, AutoScaling with virtual router supports KVM, VMware and Xenserver. + + +Prerequisites +------------- + +Before you configure an AutoScale rule, consider the following: + +- Ensure that the necessary Template is prepared before configuring AutoScale. + Firstly you must install the PV-driver or virtio driver, which helps CloudStack + collects performance parameters (CPU and memory) into Instances. Besides, when an Instance is + deployed by using a Template and when it comes up, the application should be + up and running. + +- Create an Isolated Network using a Network offering which supports Instance AutoScaling, + acquire a new IP address (it will be used as Source NAT of the Network) and create + a load balancer rule without any Instance. + For more information, see `“Configure Guest Traffic in an Advanced Zone” + `_ , + `“Acquiring a New IP Address” `_ + and `“Adding a Load Balancer Rule” `_. + + .. note:: + There is a known issue when CloudStack collects memory statistics from Instances on + KVM hosts, see https://github.com/apache/cloudstack/pull/6358 . + To get memory statistics on KVM hosts, please add the following line to + /etc/cloudstack/agent/agent.properties and restart cloudstack-agent (5/10/60 are tested ok): + + vm.memballoon.stats.period = + + .. note:: + There is a known issue when CloudStack collects average load balancer connections + from CloudStack Virtual Routers, see https://github.com/apache/cloudstack/issues/6849 + + .. note:: + The Load Balancer configurations can be found at `“Load Balancer Configurations” + `_. + + .. note:: + VmAutoScaling capability is enabled by default for Network offerings which support + load balancer. To disable it, please create a Network offering without VmAutoScaling support. + For more information, see `“Creating a New Network Offering” + `_. + + +Adding an AutoScale Instance Group +------------- + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Compute -> AutoScale Instance Groups. + +#. Click the New AutoScale Instance Group button. + +Specify the following: + +- Zone: A zone where the Instances will be deployed to. + +- Template: A Template consists of a base OS image and application. A + Template is used to provision the new Instance of an application on a + scaleup action. When an Instance is deployed from a Template, it can start + taking the traffic from the load balancer without any admin intervention. + For example, if the Instance is deployed for a Web service, it should have the + Web server running, the database connected, and so on. + +- Compute offering: A predefined set of virtual hardware attributes, + including CPU speed, number of CPUs, and RAM size, that the user can select + when creating a new Instance. Choose one of the compute offerings to be used + while provisioning an Instance as part of the scaleup action. + +- Data disk: An extra disk attached to each Instance in the Instance group. + +- Networks: The Networks of the Instances. If there are multiple networks + checked, the network of the load balancer rule will be the default Network + of the Instances. + +- Load balancing rule: When an Instance is created, it will be automatically + assigned to the load balancing rule. When an Instance is expunged, it + will be removed from the load balancing rule. + +- ScaleUp policies: The policies for ScaleUp action. When all of the conditions + in one of the ScaleUp policies are met, CloudStack will create an Instance + if the number of Instances do not exceed Max Instance. + + For more information, see `“AutoScale policies” + `_. + +- ScaleDown policies: The policies for ScaleDown action. When all of the + conditions in one of the ScaleDown policies are met, CloudStack will expunge + an Instance in the group if the number of Instances is larger than Min Instance. + + For more information, see `“AutoScale policies” + `_. + +- Name: The name of the Instance group. The name of the new Instances will use the + name of the Instance group as prefix. + +- Min Instance: The minimum number of active Instances that is assigned to + a load balancing rule. The active Instances are the application + Instances that are up and serving the traffic, and are being load balanced. + This parameter ensures that a load balancing rule has at least the + configured number of active Instances are available to serve the traffic. + +- Max Instance: Maximum number of active Instances that should be assigned + to a load balancing rule. This parameter defines the upper limit of active + Instances that can be assigned to a load balancing rule. + + Specifying a large value for the Maximum Instance parameter might result in + provisioning large number of Instances, which in turn leads to a single + load balancing rule exhausting the Instances limit specified at the + account or domain level. + +- Polling interval: Frequency in which the conditions, combination of counter, + operator and threshold, are to be evaluated before taking a scale up or + down action. The default polling interval is 30 seconds. + +- Expunge Instance Grace Period: The duration in seconds, after a scaledown action + is initiated, to wait before the Instance is expunged as part of scaledown + action. This is to ensure graceful close of any pending sessions or + transactions being served by the Instance marked for expunge. The default is 120 + seconds. + +- Create: Click Create to create the AutoScale Instance group. + + Additionally, if you want to configure the advanced settings, click Show + advanced settings, and specify the following: + +- SSH key pairs: The SSH Keys of the Instances. + + For more information, see `“Using SSH Keys for Authentication” + `_. + +- Affinity groups: The affinity groups of the Instances. + + For more information, see `“Affinity Groups” + `_. + +- User Data: The User Data of the Instances. + + For more information, see `“User Data and Metadata” + `_. + + +AutoScale Policies +------------------------------------------------- + +An AutoScale Instance Group must have one or more scale-up policies, and one or more +scale-down policies. + +Each AutoScale Policy has the following parameters: + +- Duration: The duration, in seconds, for which the conditions you specify + must be true to trigger a scale action. The conditions defined should + hold true for the entire duration you specify for an AutoScale action to be + invoked. + +- Quiet Time: This is the cool down period after an AutoScale action is + initiated. The time includes the time taken to complete provisioning an + Instance from its Template and the time taken by an application to be ready + to serve traffic. This quiet time allows the fleet to come up to a stable + state before any action can take place. The default is 300 seconds. + +- Action: The scale action. The options are ScaleUp and ScaleDown. + +- Conditions: A policy must contain at least one condition. + +Each condition in AutoScale policies has the following parameters: + +- Counter: The performance counters expose the state of the monitored + Instances. We added five new counters to work with that feature: + + - Instance CPU - average percentage + - Instance Memory - average percentage + - Public Network - mbps received per Instance + - Public Network - mbps transmit per Instance + - Load Balancer - average connections per Instance + + Remember to choose one of them. If you choose anything else, the + autoscaling will not work. + +- Operator: The following five relational operators are supported in + AutoScale feature: Greater than, Less than, Less than or equal to, Greater + than or equal to, and Equal to. + +- Threshold: Threshold value to be used for the counter. Once the counter + defined above breaches the threshold value, the AutoScale feature initiates + a scaleup or scaledown action. + + .. note:: + The counter "Instance Memory - average percentage" calculates the average memory usage + of available Instances (in Starting, Stopping, Running, Migrating states) in the + AutoScale Instance Group. On KVM/XenServer, the Instance memory usage is calculated by + + Instance memory usage percentage = (total memory - free memory) * 100 / total memory + + .. note:: + The counters "Public Network - mbps received per Instance" and + "Public Network - mbps transmit per Instance" consider all public + traffic through the VR public interface, including the traffic from/to other + Instances which are not in the AutoScale Instance group. + + .. note:: + Each network has a network rate which are configured by global configuration + network.throttling.rate and "Network rate (Mb/s)" in network offering. + + +Disabling and Enabling an AutoScale Instance Group +------------------------------------------------- + +You can view the detail of the AutoScale Instance Group. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Compute -> AutoScale Instance Groups. + +#. Select the AutoScale Instance Group you want to work with. + +|autoscale-vmgroup-details.png| + +If you want to perform any maintenance operation on the AutoScale Instances, +disable the AutoScale Instance Group. When the AutoScale Instance Group is +disabled, no scaleup or scaledown action is performed. You can use this +downtime for the maintenance activities. To disable the AutoScale Instance Group, +click the Disable AutoScale Instance Group button. + +The button toggles between enable and disable, depending on whether AutoScale +is currently enabled or not. After the maintenance operations are done, you +can enable the AutoScale Instance Group back. To enable the AutoScale Instance Group, click +the Enable AutoScale Instance Group button. + + +Updating an AutoScale Instance Group +----------------------------------- + +You can update the various parameters of Instance profile, and add or delete the +conditions in a scaleup or scaledown policy. Before you update an AutoScale Instance +Group, ensure that you disable it first by clicking the Disable AutoScale button. + +To update the AutoScale Instance Group, click the Update AutoScale Instance Group button. + +|autoscale-vmgroup-update.png| + +Updating AutoScale Instance Profile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To update the Instance Profile of the AutoScale Instance Group, click the AutoScale Instance Profile +tab, You will see the details of AutoScale Instance Profile. + +|autoscale-vmgroup-profile.png| + +then click Edit AutoScale Instance Profile button. + +|autoscale-vmgroup-profile-update.png| + +You are able to reset User Data of the Instance, by clicking Reset User Data on AutoScale Instance Group button. + +|autoscale-vmgroup-profile-reset-userdata.png| + +You are also able to update the deploy parameters of the Instances. + +|autoscale-vmgroup-deploy-parameters.png| + +The following parameters are supported. + +- affinitygroupids: The UUID of the affinity groups, separated by a single + comma character (,). + +- diskofferingid: The UUID of the data disk. + +- disksize: The size of data disk. This is valid only if the disk offering + is dynamic. + +- keypairs: The name of the SSH Key pairs, separated by a single comma + character (,). + +- networkids: The UUID of the Instance networks, separated by a single comma + character (,). + +- overridediskofferingid: The UUID of override disk offering for ROOT disk. + +- rootdisksize: The size of the ROOT disk. This overrides the size of the Instance Template. + +- securitygroupids: The UUID of security groups, separated by a single comma + character (,). This is valid only if the network provider is Netscaler. + + +Adding an AutoScale policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add a new Scale policy to the AutoScale Instance Group, click the ScaleUp policy +or ScaleDown policy tab, then click "Add policy". + +|autoscale-vmgroup-policy-new.png| + + For more information, see `“AutoScale policies” + `_. + +Updating AutoScale policies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To update the AutoScale policies of the AutoScale Instance Group, click the ScaleUp policy +or ScaleDown policy tab. + +|autoscale-vmgroup-policy.png| + +To update an existing AutoScale policies, select a policy, input the new value +of Duration or Quiet time, then click Edit button. + +To add a new condition to the policy, choose Counter and Operator and input the value, +click Add condition. + +To remove an existing condition from the policy, click Delete button of the condition. + +To update a condition in the policy, click Edit button, choose Operator and input the +value, click OK button. + +Removing an AutoScale policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To remove an existing AutoScale policies, select a policy, click "Remove policy" button. + +.. note:: + To apply the new AutoScale Instance Profile and AutoScale policies, open the AutoScale Instance + Group details, then click the Enable AutoScale Instance Group button. + +Deleting an AutoScale Instance Group +------------------------------------ + +To remove an AutoScale Instance Group, click "Delete AutoScale Instance Group" button. + +|autoscale-vmgroup-delete.png| + +AutoScale Instance Group can be removed only if there are no Instances in the group. + +To force-delete the AutoScale Instance Group, check the cleanup checkbox, then click OK button. +All the Instances in the group will be expunged. + +Runtime Considerations +---------------------- + +An administrator should not assign an Instance to a load balancing rule which is +configured for AutoScale. + +Making API calls outside the context of AutoScale, such as destroyVM, on an +autoscaled Instance leaves the load balancing configuration in an inconsistent state. +Even though the Instance is destroyed from the load balancer rule, it continues to be shown as +a service assigned to a rule inside the context of AutoScale. + + +.. |autoscale-vmgroup-delete.png| image:: /_static/images/autoscale-vmgroup-delete.png + :alt: Delete AutoScale Instance Group. +.. |autoscale-vmgroup-deploy-parameters.png| image:: /_static/images/autoscale-vmgroup-deploy-parameters.png + :alt: AutoScale Instance deploy parameters. +.. |autoscale-vmgroup-details.png| image:: /_static/images/autoscale-vmgroup-details.png + :alt: AutoScale Instance Group details. +.. |autoscale-vmgroup-policy-new.png| image:: /_static/images/autoscale-vmgroup-policy-new.png + :alt: Add new AutoScale Policy. +.. |autoscale-vmgroup-policy.png| image:: /_static/images/autoscale-vmgroup-policy.png + :alt: AutoScale Policies. +.. |autoscale-vmgroup-profile.png| image:: /_static/images/autoscale-vmgroup-profile.png + :alt: AutoScale Instance Profile. +.. |autoscale-vmgroup-update.png| image:: /_static/images/autoscale-vmgroup-update.png + :alt: Update AutoScale Instance Group. +.. |autoscale-vmgroup-profile-update.png| image:: /_static/images/autoscale-vmgroup-profile-update.png + :alt: Update AutoScale Instance Profile. +.. |autoscale-vmgroup-profile-reset-userdata.png| image:: /_static/images/autoscale-vmgroup-profile-reset-userdata.png + :alt: Reset User Data in AutoScale Instance Profile. + diff --git a/source/adminguide/autoscale_without_netscaler.rst b/source/adminguide/autoscale_without_netscaler.rst index c8f8f7f086..efeb1db366 100644 --- a/source/adminguide/autoscale_without_netscaler.rst +++ b/source/adminguide/autoscale_without_netscaler.rst @@ -26,12 +26,12 @@ Configuring AutoScale without using NetScaler What is AutoScaling? -------------------- -AutoScaling allows you to scale your back-end services or application VMs up +AutoScaling allows you to scale your back-end services or application Instances up or down seamlessly and automatically according to the conditions you define. -With AutoScaling enabled, you can ensure that the number of VMs you are using +With AutoScaling enabled, you can ensure that the number of Instances you are using seamlessly scale up when demand increases, and automatically decreases when demand subsides. Thus it helps you save compute costs by terminating underused -VMs automatically and launching new VMs when you need them, without the need +Instances automatically and launching new Instances when you need them, without the need for manual intervention. @@ -47,10 +47,10 @@ Prerequisites Before you configure an AutoScale rule, consider the following: -- Ensure that the necessary template is prepared before configuring AutoScale. +- Ensure that the necessary Template is prepared before configuring AutoScale. Firstly you must install the PV-driver, which helps Xenserver collect - performance parameters (CPU and memory) into VMs. Beside, When a VM is - deployed by using a template and when it comes up, the application should be + performance parameters (CPU and memory) into Instances. Besides, When an Instance is + deployed by using a Template and when it comes up, the application should be up and running. @@ -61,33 +61,32 @@ Specify the following: .. image:: /_static/images/autoscale-config.png -- Template: A template consists of a base OS image and application. A - template is used to provision the new instance of an application on a - scaleup action. When a VM is deployed from a template, the VM can start +- Template: A Template consists of a base OS image and application. A + Template is used to provision the new Instance of an application on a + scaleup action. When an Instance is deployed from a Template, it can start taking the traffic from the load balancer without any admin intervention. - For example, if the VM is deployed for a Web service, it should have the + For example, if the Instance is deployed for a Web service, it should have the Web server running, the database connected, and so on. - Compute offering: A predefined set of virtual hardware attributes, including CPU speed, number of CPUs, and RAM size, that the user can select - when creating a new virtual machine instance. Choose one of the compute - offerings to be used while provisioning a VM instance as part of scaleup - action. + when creating a new Instance. Choose one of the compute offerings to be used + while provisioning an Instance as part of scaleup action. -- Min Instance: The minimum number of active VM instances that is assigned to - a load balancing rule. The active VM instances are the application - instances that are up and serving the traffic, and are being load balanced. +- Min Instance: The minimum number of active Instances that is assigned to + a load balancing rule. The active Instances are the application + Instances that are up and serving the traffic, and are being load balanced. This parameter ensures that a load balancing rule has at least the - configured number of active VM instances are available to serve the traffic. + configured number of active Instances are available to serve the traffic. -- Max Instance: Maximum number of active VM instances that should be assigned +- Max Instance: Maximum number of active Instances that should be assigned to a load balancing rule. This parameter defines the upper limit of active - VM instances that can be assigned to a load balancing rule. + Instances that can be assigned to a load balancing rule. - Specifying a large value for the maximum instance parameter might result in - provisioning large number of VM instances, which in turn leads to a single - load balancing rule exhausting the VM instances limit specified at the - account or domain level. + Specifying a large value for the maximum Instance parameter might result in + provisioning large number of Instances, which in turn leads to a single + load balancing rule exhausting the Instances limit specified at the + Account or domain level. Specify the following scale-up and scale-down policies: @@ -97,7 +96,7 @@ Specify the following scale-up and scale-down policies: invoked. - Counter: The performance counters expose the state of the monitored - instances. We added two new counter to work with that feature: + Instances. We added two new counter to work with that feature: - Linux User CPU [native] - percentage - Linux User RAM [native] - percentage @@ -123,15 +122,15 @@ Specify the following scale-up and scale-down policies: down action. The default polling interval is 30 seconds. - Quiet Time: This is the cool down period after an AutoScale action is - initiated. The time includes the time taken to complete provisioning a VM - instance from its template and the time taken by an application to be ready + initiated. The time includes the time taken to complete provisioning an + Instance from its Template and the time taken by an application to be ready to serve traffic. This quiet time allows the fleet to come up to a stable state before any action can take place. The default is 300 seconds. -- Destroy VM Grace Period: The duration in seconds, after a scaledown action - is initiated, to wait before the VM is destroyed as part of scaledown +- Destroy Instance Grace Period: The duration in seconds, after a scaledown action + is initiated, to wait before the Instance is destroyed as part of scaledown action. This is to ensure graceful close of any pending sessions or - transactions being served by the VM marked for destroy. The default is 120 + transactions being served by the Instance marked for destroy. The default is 120 seconds. - Apply: Click Apply to create the AutoScale configuration. @@ -140,7 +139,7 @@ Specify the following scale-up and scale-down policies: Disabling and Enabling an AutoScale Configuration ------------------------------------------------- -If you want to perform any maintenance operation on the AutoScale VM instances, +If you want to perform any maintenance operation on the AutoScale Instances, disable the AutoScale configuration. When the AutoScale configuration is disabled, no scaleup or scaledown action is performed. You can use this downtime for the maintenance activities. To disable the AutoScale @@ -168,11 +167,11 @@ click the Enable AutoScale button. Runtime Considerations ---------------------- -An administrator should not assign a VM to a load balancing rule which is +An administrator should not assign an Instance to a load balancing rule which is configured for AutoScale. Making API calls outside the context of AutoScale, such as destroyVM, on an -autoscaled VM leaves the load balancing configuration in an inconsistent state. -Though VM is destroyed from the load balancer rule, it continues be showed as -a service assigned to a rule inside the context of AutoScale. +autoscaled Instance leaves the load balancing configuration in an inconsistent state. +Even though the Instance is destroyed from the load balancer rule, it continues to be shown +as a service assigned to a rule inside the context of AutoScale. diff --git a/source/adminguide/backup_and_recovery.rst b/source/adminguide/backup_and_recovery.rst index aaa6e565aa..f07e6649bd 100644 --- a/source/adminguide/backup_and_recovery.rst +++ b/source/adminguide/backup_and_recovery.rst @@ -17,19 +17,28 @@ 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 +provides CloudStack with users the ability to back up their Guest Instances 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 +operations, from the vendor specific commands 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 +- KVM with DELL EMC Networker +- KVM with NAS B&R Plugin (4.20 onwards) See the Veeam Backup and Recovery plugin documentation for plugin specific information. -:ref:`Veeam Backup and Recovery Plugin` +:ref:`Veeam Backup and Replication Plugin` + +See the DELL EMC Networker Backup and Recovery plugin documentation for plugin specific information. +:ref:`DELL EMC Networker Backup and Recovery Plugin` + +See the NAS Backup and Recovery plugin documentation for plugin specific information. +:ref:`NAS Backup and Recovery Plugin` + Backup and Recovery Concepts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -45,14 +54,14 @@ A user signs up for a 'Gold' offering, which might give them a RPO of 12 hours a 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. +To use an SLA based backup policy the user adds their Instances to the offering/policy. The job then runs at its predetermined times and 'includes' the +Instance when it runs. A user can remove the Instance 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 +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. +size of the Instance(s) being backed up. -Adhoc and user scheduled backups are created and managed in the same fashion as volume snapshots are. +Adhoc and user scheduled backups are created and managed in the same fashion as Volume Snapshots are. Configuring Backup and Recovery @@ -68,7 +77,7 @@ the Global Settings area of the CloudStack UI. 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.provider.plugin The backup provider (plugin) name. For example: 'dummy', 'veeam', 'networker' and 'nas'. 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. ================================= ======================== @@ -83,7 +92,7 @@ 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 +particular zone, as well as manage a backup offering's lifecycle. 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. @@ -93,7 +102,7 @@ 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 +- **importBackupOffering**: 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 @@ -107,18 +116,18 @@ 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. + Template jobs which CloudStack retrieves from the connected provider. |B&R-backup_offering_policy.png| |B&R-backup_offering.png| -Creating VM Backups ---------------------- +Creating Instance 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. +remove an Instance from a backup offering. |B&R-assignOffering.png| @@ -126,64 +135,185 @@ 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. +schedules, user will be allowed to define a backup schedule for an Instance that is +assigned to a backup offering using UI and API. An Instance with backup will not be +allowed to add/remove volumes similar to Instance Snapshots. -To trigger an adhoc backup of a VM, navigate to the instance and click on the 'Create Backup' +To trigger an adhoc backup of an Instance, navigate to the Instance and click on the 'Create Backup' icon. |B&R-createBackup.png| -To setup a recurring backup schedule, navigate to the instance and click on the 'Backup Schedule' +To setup a recurring backup schedule, navigate to the Instance and click on the 'Configure Backup Schedule' icon. |B&R-BackupSchedule.png| -Then set the time and frequency of the backups, click 'Configure' and then 'Close' +Then set the Interval type, timezone, time of taking the backup and maximum numbers of backups to retain. |B&R-BackupScheduleEntry.png| -Restoring VM Backups ---------------------- +Restoring Instance Backups +-------------------------- + +Users will need to stop an Instance to restore to any existing Instance backup, restoration +of an expunged Instance will not restore nics and recovery any network which may/may +not exist. User may however restore a specific volume from an Instance backup and attach +that volume to a specified Instance. + +Creating a new Instance from Backup +----------------------------------- + +Since CloudStack 4.21, users can remove the backup offering and expunge or unmanage an instance +that has existing backups, for the supported backup providers — Dummy, NAS, and Veeam. +Additionally, users can create a new instance from a backup using any of these providers. + +Each backup now includes metadata that captures the instance’s configuration at the time of backup including service offering, +template, disk offerings for all data volumes, attached networks, and instance-specific settings. +The new instance will be created with the same configuration and data as the original instance at the time the backup was taken. + +.. warning:: + Users should ensure that the entry for the expunged or unmanaged instance is not purged from the database, as the backup framework relies on it to function correctly. + +|B&R-CreateInstanceFromBackup.png| + +Users also have the option to customize the configuration of the new instance, similar to deploying a new instance from scratch. +The deployment form will be pre-filled with the values captured in the backup, but users can modify them as needed. +However, the number of volumes in the new instance must match the number of volumes in the backup. +If volume sizes are customized, users must ensure that each volume is at least as large as the corresponding volume in the backup. +Advanced settings are not pre-filled in the form by default, but if left unset, they will automatically be retrieved from the backup metadata. +The Template and ISO can only be updated via the UI if the UUID stored in the backup is no longer available in the environment. + +If the original instance from which the backup was created has been expunged, users will be presented with an option to reuse thesame IP address and +MAC address stored in the backup metadata. The new instance will be assigned the same IP and MAC address, provided they are still available in the network. + +|B&R-ConfigureInstance.png| + +If one or few of the resources stored in the backup such as template, networks etc are no longer available +in the system, the user will be prompted to reconfigure the Instance before creating it from backup. + +.. note:: + If the backup was created in a release prior to 4.21, the backup metadata won't contain the instance configuration details, + so users would have to fill in the required details by clicking on the Configure Instance button. + +Creating a New Instance from Backup in Another Zone +--------------------------------------------------- + +Since **Apache CloudStack 4.22**, users can create a new Instance from a Backup in another Zone. +i.e, the Instance being created can be on a different Zone from the Zone in which the Backup was created. +This can be used to implement Disaster Recovery capabilities with Instance Backups. +Currently, this capability is supported only by the **NAS Backup & Recovery plugin**. + +When creating a Backup Repository, the administrator can enable the **Cross-Zone Instance Creation** option. +This allows the repository to be used for creating Instances in other Zones. The setting can be changed later as well +using the Edit Backup Repository action button. -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. +|B&R-Cross-Zone-Enable-Add.png| + +Once Cross-Zone Instance Creation is enabled for a Backup Repository, users will see the option to **select a Zone** while creating a new Instance from a Backup. + +|B&R-Cross-Zone-Select-Zone.png| + +The new Instance will be created in the selected Zone, with the configuration either inherited from the backup or chosen by the user. +Configurations stored in the backup are automatically selected if the same resources are present in the destination Zone. + +For example, if the same template exists in both the source and destination Zones, it will be auto-selected. +Users will still need to manually select configurations that are unique to a single Zone, such as networks. + +Points to Note +~~~~~~~~~~~~~~ + +- A Cross-Zone enabled Backup Repository can be used to create Instances in **all Zones** within the CloudStack environment. +- The Backups can be taken only from the original Zone. +- The administrator must ensure that the Backup Repository is **reachable and mountable** from hosts in other Zones. +- Restore operations are performed by mounting the Backup Repository over **NFS, CIFS, or CephFS** (depending on configuration), + and then copying the backup files to Primary Storage. + +Extending the Functionality for DRaaS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Administrators can extend this feature to implement Disaster Recovery as a Service (DRaaS) by adding additional configuration and instrumentation. +Two common approaches are: + +1. **Zone-Local Repository** + + - Configure a Backup Repository that is local to the source Zone. + - Add this repository to the Zone and enable Cross-Zone Instance Creation. + - In other Zones, configure NAS servers and synchronize backup files in the background between the source repository and the NAS servers in those Zones. + - Use DNS to resolve the repository URL to the local NAS server in each Zone, ensuring Instance creation from Backup always use the closest copy. + +2. **Global Repository with WAN Optimizations** + + - Configure a single global Backup Repository accessible from all Zones. + - NFS performance over WAN may become a bottleneck for Cross-Zone Instance creation scenarios. + To improve NFS performance over WAN, the following NFS mount options are recommended: + + - ``nconnect=16``: Open multiple TCP connections to the NFS server. + - ``rsize=1048576``: Use a larger chunk size for reads. + - ``wsize=1048576``: Use a larger chunk size for writes. + - The actual read and write chunk sizes may be increased further, depending on the NFS server’s capabilities. 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. +- **assignVirtualMachineToBackupOffering**: adds an Instance to a backup offering. +- **removeVirtualMachineFromBackupOffering**: removes an Instance from a backup offering, if forced `true` parameter is passed this may also + remove any and all the backups of an Instance associated with a backup offering. +- **createBackupSchedule**: creates a backup schedule for an Instance. - **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). +- **listBackupSchedule**: returns backup schedule of an Instance if defined. +- **deleteBackupSchedule**: deletes backup schedule of an Instance. +- **createBackup**: creates an adhoc backup for an Instance. +- **deleteBackup**: deletes an Instance 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. - +- **restoreBackup**: restore a previous Instance backup in-place of a stopped or destroyed Instance. +- **restoreVolumeFromBackupAndAttachToVM**: restore and attach a backed-up volume (of an Instance backup) to a specified Instance. +- **createVMFromBackup**: create a new Instance from a backup. + + +Configuring resource limits on Backups +-------------------------------------- +Administrators can enforce limits on the maximum number of backups that can be taken and +the total backup storage size that can be used at an account, domain and project level. +Administrators can do this by going to the configure limits tab in accounts, domains and projects +similar to when enforcing resource limits on volumes, primary storage usage etc. + +Unlike other resources like volumes, backup limits take into account the physical used size +and not the allocated size of the backup. This is because the backup once taken can never +grow into the allocated size. At the time of backup creation, Cloudstack doesn't know the +size of the backup that will be taken, so it uses the physical size of the volumes to be +backed up from Volume Stats to calculate the backup size for checking resource limits. +If Volume Stats are not present, then the virtual size of the volumes is used to calculate +the backup size, although the actual backup size may be less than the size use to do resource limit check. .. |B&R-assignOffering.png| image:: /_static/images/B&R-assignOffering.png - :alt: Assigning an SLA/Policy to a VM. + :alt: Assigning an SLA/Policy to an Instance. :width: 400 px .. |B&R-backup_offering_policy.png| image:: /_static/images/B&R-backup_offering_policy.png :alt: Importing an SLA/Policy offering. :width: 300 px .. |B&R-backup_offering.png| image:: /_static/images/B&R-backup_offering.png - :alt: Importing a template backup offering. + :alt: Importing a Template backup offering. :width: 300 px .. |B&R-createBackup.png| image:: /_static/images/B&R-createBackup.png - :alt: Triggering an adhoc backup for a VM. + :alt: Triggering an adhoc backup for an Instance. :width: 400 px .. |B&R-BackupSchedule.png| image:: /_static/images/B&R-BackupSchedule.png - :alt: Creating a backup schedule for a VM. + :alt: Creating a backup schedule for an Instance. :width: 400 px .. |B&R-BackupScheduleEntry.png| image:: /_static/images/B&R-BackupScheduleEntry.png - :alt: Creating a backup schedule for a VM. + :alt: Creating a backup schedule for an Instance. + :width: 400px +.. |B&R-CreateInstanceFromBackup.png| image:: /_static/images/B&R-CreateInstanceFromBackup.png + :alt: Creating a new Instance from a backup. :width: 400px +.. |B&R-ConfigureInstance.png| image:: /_static/images/B&R-ConfigureInstance.png + :alt: Configure Instance parameters before creating it from backup. + :width: 700px +.. |B&R-Cross-Zone-Enable-Add.png| image:: /_static/images/B&R-Cross-Zone-Enable-Add.png + :alt: Enable Cross-Zone Instance Creation on Backup Repository + :width: 400px +.. |B&R-Cross-Zone-Select-Zone.png| image:: /_static/images/B&R-Cross-Zone-Select-Zone.png + :alt: Select Zone when creating Instance from Backup + :width: 700px + diff --git a/source/adminguide/best_practices.rst b/source/adminguide/best_practices.rst new file mode 100644 index 0000000000..a1795de466 --- /dev/null +++ b/source/adminguide/best_practices.rst @@ -0,0 +1,28 @@ +.. 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. + + +Best Practices +============== + +This section provides the best practices to follow for your cloud. + +The following are some of the best practices: + +- Configure 'api.allowed.source.cidr.list' at cloud level or an account + level to limit source IPs where the API requests are allowed from. + +- Setup fail2ban or similar tools to avoid any brute-force attempts + for any operations. diff --git a/source/adminguide/clusters.rst b/source/adminguide/clusters.rst new file mode 100644 index 0000000000..12859a3ea1 --- /dev/null +++ b/source/adminguide/clusters.rst @@ -0,0 +1,131 @@ +.. 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. + + +Adding Clusters +--------------- + +Additional clusters can be added at any time to add a new set of hosts. +For requirements and instructions, see :ref:`adding-a-cluster`. + + +CloudStack DRS +-------------- +DRS is a process that can rebalance instances across hypervisor hosts in a cluster as defined by the algorithm selected. +There are two algorithms available: + +#. **Condensed** spread instances across hosts as densely as possible. + This is useful for reducing the number of hosts used. +#. **Balanced** spread instances across hosts as evenly as possible. + This is useful for reducing the load on each host. This is the default algorithm. + +.. note:: + Deployment planner will not consider DRS while deploying instances. + +Configuring DRS +~~~~~~~~~~~~~~~ +Following are the configuration parameters for DRS. + +.. list-table:: DRS related cluster parameters + :header-rows: 1 + + * - Parameter + - Default + - Description + * - ``drs.plan.expire.interval`` + - `30` + - The interval in days after which the DRS events will be cleaned up. + * - ``drs.automatic.enable`` + - `false` + - Enable/disable automatic DRS on a cluster. + * - ``drs.automatic.interval`` + - `60` + - The interval in minutes after which a periodic background thread will schedule DRS for a cluster. + * - ``drs.max.migrations`` + - `50` + - Maximum number of instances to be migrated in one DRS execution. + * - ``drs.algorithm`` + - `condensed` + - DRS algorithm to be executed on the cluster. Available algorithms - `condensed`, `balanced`. + * - ``drs.imbalance`` + - `0.4` + - Percentage (as a value between 0.0 and 1.0) of imbalance allowed in the cluster. 1.0 means no imbalance + is allowed and 0.0 means imbalance is allowed. + * - ``drs.metric`` + - `memory` + - The allocated resource metric to use for measuring imbalance for a cluster. Possible values are memory, cpu. + +.. note:: + Scope of ``drs.plan.expire.interval`` is global and for rest is cluster level. + +.. note:: + Very high value for ``drs.max.migrations`` can result in management server using up all of it's workers for DRS tasks + and not being able to execute other tasks. + +There are some advanced parameters that can be configured for DRS. These parameters impact the way imbalance is calculated +for a cluster. Do not change these parameters unless you know what you are doing. + +.. list-table:: Advanced DRS related cluster parameters + :header-rows: 1 + + * - Parameter + - Default + - Description + * - ``drs.metric.type`` + - `used` + - The metric type used to measure imbalance in a cluster. This can completely change the imbalance value. + Possible values are free, used. + * - ``drs.metric.use.ratio`` + - `true` + - Whether to use ratio of selected metric & total. Useful when the cluster has hosts with different capacities. + * - ``drs.imbalance.condensed.skip.threshold`` + - `0.95` + - Threshold to ignore the metric for a host while calculating the imbalance to decide whether DRS is required for + a cluster. This is to avoid cases when the calculated imbalance gets skewed due to a single host having a very + high/low metric value resulting in imbalance being higher than 1. If ``drs.metric.type`` is ``free``, set a lower + value and if it is ``used`` set a higher value. The value should be between `0.0` and `1.0`. + This is applicable only for Condensed algorithm. + +Executing manual DRS on a cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +DRS can also be manually executed for a cluster. + +Follow these steps to execute DRS for a cluster using the UI: + +#. Configure DRS parameters as per the requirement. + |drs-cluster-settings.png| +#. Open DRS tab for the cluster. + |drs-cluster-tab.png| +#. Select the iteration percentage to execute for the cluster. +#. Click on `Generate DRS Plan` button. A modal will appear showing migrations + for that cluster as per the configured algorithm. + |drs-plan.png| +#. Validate the migrations, and click on `Execute` button to execute the + suggested migrations. + + +.. note:: + Only one DRS process can run for a cluster at a time. If you try to run DRS while another + DRS process is running, the second process will fail. + + +.. |drs-cluster-settings.png| image:: /_static/images/drs-cluster-settings.png + :alt: DRS settings for a cluster. + +.. |drs-cluster-tab.png| image:: /_static/images/drs-cluster-tab.png + :alt: DRS tab for a cluster. + +.. |drs-plan.png| image:: /_static/images/drs-plan.png + :alt: DRS plan for a cluster. diff --git a/source/adminguide/events.rst b/source/adminguide/events.rst index 629fcc45de..b3444730e0 100644 --- a/source/adminguide/events.rst +++ b/source/adminguide/events.rst @@ -50,8 +50,8 @@ notification is achieved by implementing the concept of event bus abstraction in the Management Server. A new event for state change, resource state change, is introduced as -part of Event notification framework. Every resource, such as user VM, -volume, NIC, network, public IP, snapshot, and template, is associated +part of Event notification framework. Every resource, such as user Instance, +volume, NIC, network, public IP, Snapshot, and Template, is associated with a state machine and generates events as part of the state change. That implies that a change in the state of a resource results in a state change event, and the event is published in the corresponding state @@ -59,6 +59,14 @@ machine on the event bus. All the CloudStack events (alerts, action events, usage events) and the additional category of resource state change events, are published on to the events bus. +.. note:: + Alerts for some more important events will be sent multiple + times. This is due to the nature of guarding + certain resources from multiple threads in the code, to make sure + that events are not missed. Examples are "Host down" or + "HA starting VM". These are considered too important to not send + immediately and hence a check if they are already queued can not be done. + Implementations ~~~~~~~~~~~~~~~ An event bus is introduced in the @@ -73,6 +81,13 @@ in the AMQP server. Additionally, both an in-memory implementation and an Apache Kafka implementation are also available. + +.. note:: + On upgrading from 4.19.x or lower, existing AMQP or Kafka integration + configurations should be moved from folder + ``/etc/cloudstack/management/META-INF/cloudstack/core`` to + ``/etc/cloudstack/management/META-INF/cloudstack/event`` + Use Cases ~~~~~~~~~ @@ -101,7 +116,7 @@ As a CloudStack administrator, perform the following one-time configuration to enable event notification framework. At run time no changes can control the behaviour. -#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/core`` +#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/event`` #. Inside that folder, open ``spring-event-bus-context.xml``. @@ -113,11 +128,11 @@ changes can control the behaviour. - port : The port on which RabbitMQ server is running. - - username : The username associated with the account to access the + - username : The username associated with the Account to access the RabbitMQ server. - password : The password associated with the username of the - account to access the RabbitMQ server. + Account to access the RabbitMQ server. - exchange : The exchange name on the RabbitMQ server where CloudStack events are published. @@ -203,6 +218,23 @@ changes can control the behaviour. #. Restart the Management Server. +#. CloudStack creates the exchange ‘cloudstack-events’ which will receive messages containing CloudStack events; however will be no queues created. + + To create a queue and bind with cloudstack-events the following steps are needed: + + - Go to Queues tab and add a queue, e.g. 'cloudstack-queue’ + - Go to Exchanges tab and Bind to queue cloudstack-queue with the desired ‘Routing key’. + + +#. Routing keys + + The routing key is a list of words, delimited by a period ("."). CloudStack builds routing keys according to each event type, some examples are: + + Some example of routing keys that match CloudStack events: + - A pound symbol (“#”) indicates a match on zero or more words; thus, it will match any possible set of words; + - Asterisk (“*”) matching any word and the period (“.”) delimiting example '\*.*.*.*.*' + + Kafka Configuration ~~~~~~~~~~~~~~~~~~~ @@ -214,9 +246,22 @@ changes can control the behaviour. which contains valid kafka configuration properties as documented in http://kafka.apache.org/documentation.html#newproducerconfigs The properties may contain an additional ``topic`` property which if not provided will default to ``cloudstack``. While ``key.serializer`` and ``value.serializer`` are usually required for a producer to correctly start, they may be omitted and - will default to ``org.apache.kafka.common.serialization.StringSerializer``. + will default to ``org.apache.kafka.common.serialization.StringSerializer``. A sample example which will be used by cloudstack for exporting of events + + .. parsed-literal:: + + cat /etc/cloudstack/management/kafka.producer.properties + + bootstrap.servers=:9092 + acks=all + topic=cs + retries=1 + + -#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/core`` + + +#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/event`` #. Inside that folder, open ``spring-event-bus-context.xml``. @@ -251,10 +296,10 @@ The events log records three types of standard events. - WARN. This event is generated in the following circumstances. - - When a network is disconnected while monitoring a template + - When a network is disconnected while monitoring a Template download. - - When a template download is abandoned. + - When a Template download is abandoned. - When an issue on the storage server causes the volumes to fail over to the mirror storage server. @@ -273,10 +318,10 @@ The events log records three types of standard events. - WARN. This event is generated in the following circumstances. - - When a network is disconnected while monitoring a template + - When a network is disconnected while monitoring a Template download. - - When a template download is abandoned. + - When a Template download is abandoned. - When an issue on the storage server causes the volumes to fail over to the mirror storage server. @@ -291,7 +336,7 @@ Event Log Queries Database logs can be queried from the user interface. The list of events captured by the system includes: -- Virtual machine creation, deletion, and on-going management +- Instance creation, deletion, and on-going management operations - Virtual router creation, deletion, and on-going management operations @@ -366,3 +411,9 @@ Procedure date. #. Click OK. + + +Webhooks +-------- + +.. include:: events/webhooks.rst diff --git a/source/adminguide/events/webhooks.rst b/source/adminguide/events/webhooks.rst new file mode 100644 index 0000000000..023b58d317 --- /dev/null +++ b/source/adminguide/events/webhooks.rst @@ -0,0 +1,199 @@ +.. 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. + + +Webhooks allow external services to be notified when certain events happen. +CloudStack allows provisioning webhooks for all account roles and for various +scopes. +This allows users to consume event notifications without any external services +such as an event streaming platforms. + +Webhooks can be managed using both API and UI. CloudStack provides following +APIs for webhooks: + + .. cssclass:: table-striped table-bordered table-hover + + ====================== =========================== + API Description + ====================== =========================== + createWebhook Creates a Webhook + listWebhooks Lists Webhooks + updateWebhook Updates a Webhook + deleteWebhook Deletes a Webhook + listWebhookDeliveries Lists Webhook deliveries + deleteWebhookDelivery Deletes Webhook delivery(s) + executeWebhookDelivery Executes a Webhook delivery + ====================== =========================== + +In the UI, webhooks can be managed under *Tools > Webhooks* menu. + + |webhooks.png| + + +Creating a webhook +~~~~~~~~~~~~~~~~~~ + +Any CloudStack user having createWebhook API access can create a new webhook +for the event notifications. + +To create a webhook: + +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Tools and choose Webhooks. + +#. Click Create Webhook. + +#. In the dialog, make the following choices: + + - **Name**. Any desired name for the webhook. + + - **Description**. A short description of the webhook. + + - **Scope**. (Available only for ROOT admins or domain admins). Scope + of the webhook. The value can be Local, Domain or Global. + Local - only events associated with the owner account will be notified. + Domain - events associated with domain will be notified. + Global - all events will be notified. This is available only for ROOT + admin account. + For a normal user account, webhooks can be created with Local scope + only. + + - **Domain**. An optional domain for the Webhook. If the account parameter + is used, domain must also be used. + + - **Account**. An optional account for the webhook. Must be used with + domain. + + - **Payload URL**. The payload URL of the Webhook. All events for the + webhook will posted on this URL. + + - **SSL Verification**. An optional parameter to specify whether the HTTP + POST requests for event notifications must be sent with strict SSL + verification request when a HTTPS payload URL is used. + + - **Secret Key**. An option secret key parameter which can be used to sign + the HTTP POST requests for event notifications with HMAC. + + - **Enabled**. To specify whether the webhook be created with enabled or + disabled state + + |create-webhook.png| + + +Working with webhook deliveries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack attempts webhook deliveries using a thread pool with given retries. +The following global configuration can be used to configure thread pool size +for deliveries: + + - **webhook.delivery.thread.pool.size**: Size of the thread pool for webhook + deliveries. + + +Also, the number attempts for a particular event notification and the timeout +for one particular attempt can be configured using the following domain-level +configurations: + + - **webhook.delivery.retries**: Number of tries to be made for a webhook + delivery. + + - **webhook.delivery.timeout**: Wait timeout (in seconds) for a webhook + delivery attempt. + +.. note:: + The onus of dealing with the duplicate event deliveries lies with the payload + server or application. During delivery, when the server doesn't respond in a + timely manner or returns a failure CloudStack will re-attempt the delivery of + the event, based on the above global settings, irrespective of the fact whether + the server already received the event in any previous attempts. + + +CloudStack allows retrieving recent deliveries for a webhook with details such +as event, headers, payload, response, success, duration, etc. +In the UI, these can be accessed under Recent deliveries tab in the Webhook +detail view. +The user can redeliver an existing delivery. To check the working of the +webhook consumer test deliveries can made. Test deliveries are not recorded +by CloudStack. + + |webhook-deliveries.png| + +The administrator can configure storage of webhook deliveries using the +following global configurations: + + - **webhook.deliveries.limit**: Limit for number of deliveries to keep + in DB per webhook. Default value is 10. + + - **webhook.deliveries.cleanup.interval**: Interval (in seconds) for + cleaning up webhook deliveries. Default value is 3600 or 1 hour. + + - **webhook.deliveries.cleanup.initial.delay**: Initial delay (in seconds) + for webhook deliveries cleanup task. Default value is 180. + +Based on the above configurations CloudStack will purge older deliveries in +the database using a repeatedly running task. + +For a webhook delivery, CloudStack sends a HTTP POST request with event data +as the payload. The following custom headers are sent with the request: + + - **X-CS-Event-ID**. Event ID for which the webhook delivery is made. + + - **X-CS-Event**. Event for for which the webhook delivery is made. + + - **User-Agent**. In the format - *CS-Hookshot/*. Here + ACCOUNT_ID is the ID of the account which triggered the event. + + - **X-CS-Signature**. HMAC SHA256 signature created using the webhook + secret key and the delivery payload. It is sent only when secret key + is specified for the webhook. + + +Working with HTTPS webhook payload URL with self-signed certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Generate a self signed certificate for the server, make sure to mention the IP address of the server when it prompts. + + .. parsed-literal:: + + openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365 + +#. Copy the generated cert.pem to the management server(s). + +#. Import the certificate for JDK on the management server(s) + + .. parsed-literal:: + + cp /etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/cacerts /etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/jssecacerts + + keytool -importcert -file /root/kiran/cert.pem -alias webhook -keystore /etc/java/java-17-openjdk/java-17-openjdk-17.0.10.0.7-2.0.1.el8.x86_64/lib/security/jssecacerts -storepass changeit + +4. Test the webhook. + + + +.. Images + + +.. |webhooks.png| image:: /_static/images/webhooks.png +.. |create-webhook.png| image:: /_static/images/create-webhook.png +.. |webhook-deliveries.png| image:: /_static/images/webhook-deliveries.png + + + + + + diff --git a/source/adminguide/extensions.rst b/source/adminguide/extensions.rst new file mode 100644 index 0000000000..2c6b7308e0 --- /dev/null +++ b/source/adminguide/extensions.rst @@ -0,0 +1,108 @@ +.. 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. + + +Extensions +========== + +Extensions are a new mechanism introduced in Apache CloudStack to allow administrators to extend the platform's functionality by integrating external systems or custom workflows. Currently, CloudStack supports a single extension type called Orchestrator. + +In the UI, extensions can be managed under *Extensions* menu. + + |extensions.png| + +Overview +^^^^^^^^ + +An extension in CloudStack is defined as an external binary (written in any programming language) that implements specific actions CloudStack can invoke. This allows operators to manage resource lifecycle operations outside CloudStack, such as provisioning VMs in third-party systems or triggering external automation pipelines. + +Extensions are managed through the API and UI, with support for configuration, resource mappings, and action execution. + + |create-extension.png| + +Configuration +^^^^^^^^^^^^^ + +Administrators can define and manage the following components of an extension: + + - Path: A path to a file or script that will be executed during extension operations. + + - Configuration Details: Key-value properties used by the extension at runtime. + + - Resource Mappings: Association between extensions and CloudStack resources such as clusters, etc. + +Path and Availabilty +^^^^^^^^^^^^^^^^^^^^ + +The path for an extension can point to any binary or executable script. If no explicit path is provided, CloudStack uses a default base Bash script. The state of the path is validated across all management servers. In the UI, the Availabilty is displayed as Not Ready if the file is missing, inaccessible, or differs across management servers. + +All extension files are stored under a directory named after the extension within `/usr/share/cloudstack-management/extensions`. + +Payload +^^^^^^^ + +CloudStack sends structured JSON payloads to the extension binary during each operation. These payloads are written to .json files stored under `/var/lib/cloudstack/management/extensions`. The extension binary is expected to read the file and return an appropriate result. CloudStack automatically attempts to clean up payload files older than one day. + +Orchestrator Extension +^^^^^^^^^^^^^^^^^^^^^^ + +An Orchestrator extension enables CloudStack to delegate VM orchestration to an external system. Key features include: + + - Cluster Mapping: Orchestrator extensions can be associated with one or more CloudStack clusters. + + - Hosts: Multiple hosts can be added to such clusters, ideally pointing to different physical or external hosts. + + - Instance Lifecycle Supported: Orchestrator extensions can handle basic VM actions like prepare, deploy, start, stop, reboot, status and delete. + + - Console Access: Instances can be accessed either via VNC consoles or through a URL, depending on the capabilities of the orchestrator extension. CloudStack retrieves console details from extensions using the ``getconsole`` action and either forwards them to the Console Proxy VM (CPVM) (for VNC access) or provides the external console URL to the user. Since 4.22.0, out-of-the-box console access support is available for instances deployed using the in-built Proxmox extension. See :ref:`Console Access for Instances with Orchestrator Extensions `for details on adding console access support in developed extensions. + + - Configuration Details: Key-value configuration details can be specified at different levels - extension, cluster mapping, host, template, service offering, instance. + + - Custom Actions: Admins can define custom actions beyond the standard VM operations. + + - Instance Preparation: Orchestrator extensions can optionally perform a preparation step during instance deployment. This step is executed before the instance is started on the external system. It allows the extension to update certain instance details in CloudStack. CloudStack sends a structured JSON containing the instance configuration, and the extension can respond with the values it wishes to modify. Currently, only a limited set of fields can be updated: the instance’s VNC password, MAC address, details, and the IPv4/IPv6 addresses of its NICs. + + - Networking: If networking is setup properly on the external system (See :ref:`in-built extensions networking ` for more details.), the Virtual Router in CloudStack can connect to the external VMs and provide DHCP, DNS, and routing services. + + **Note**: User data and ssh-key injection from within CloudStack is not supported for the external VMs in this release. The External systems should handle user-data and ssh-key injections natively using other mechanisms. + + |extension.png| + + +CloudStack provides built-in Orchestrator Extensions for Proxmox, Hyper-V, and MaaS, which work with their respective environments out of the box. + +.. note:: + - When a CloudStack host linked to an orchestrator extension is placed into Maintenance mode, all running instances on the host will be stopped. + + - For hosts linked to extensions, CloudStack will report zero for CPU and memory capacity, and host metrics will reflect the same. During instance deployment, capacity checks are the responsibility of the extension executable; CloudStack will not perform any capacity calculations. + + - Some of the features that rely on interaction with VMs, such as VM snapshots, live migration, VM scaling, VM autoscaling groups, VNF appliance, Kubernetes clusters, etc are currently not supported for instances managed by orchestrator extensions. + +.. include:: extensions/custom_actions.rst + +.. include:: extensions/inbuilt_extensions.rst + +.. include:: extensions/limitations.rst + +.. include:: extensions/troubleshooting.rst + +.. include:: extensions/developer.rst + +.. Images + + +.. |extensions.png| image:: /_static/images/extensions.png +.. |create-extension.png| image:: /_static/images/create-extension.png +.. |extension.png| image:: /_static/images/extension.png diff --git a/source/adminguide/extensions/custom_actions.rst b/source/adminguide/extensions/custom_actions.rst new file mode 100644 index 0000000000..c250019678 --- /dev/null +++ b/source/adminguide/extensions/custom_actions.rst @@ -0,0 +1,62 @@ +.. 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. + + +Custom Actions +^^^^^^^^^^^^^^ + +In addition to standard instance operations, extensions support custom actions. These can be configured via UI in the extension details view or the addCustomAction API. The extension binary or script must implement handlers for these action names and process any provided parameters. + + |add-custom-action.png| + +Description, allowed role types, parameters, success/error messages, configuration details, timeout can be defined during creation or update. +Alowed role types can be one or more of Admin, Resource Admin, Domain Admin, User. +Success and error messages will be used and returned during action execution. They allow string expansion and the following can be used to customise messages: + + - {{actionName}} for showing name of the action + - {{extensionName}} for showing name of the extension + - {{resourceName}} for showing name of the resource + +An example usage can be - "Successfully completed {{actionName}} for {{resourceName}} using {{extensionName}}". +Configuration details can be key-value pairs which will be passed to the extension during action execution. +Timeout value can be configured to adjust wait time for action completion. + +A single parameter can have the following details: + + - **name**: Name of the parameter. + + - **type**: Type of the parameter. It can be one of the following: BOOLEAN, DATE, NUMBER, STRING + + - **validationformat**: Validation format for the parameter value. Supported only for NUMBER and STRING type. For NUMBER, it can be NONE or DECIMAL. For STRING, it can be NONE, EMAIL, PASSWORD, URL, UUID. + + - **valueoptions**: Options for the value of the parameter. This is allowed only for NUMBER and STRING type. + + +Running Custom Action +~~~~~~~~~~~~~~~~~~~~~ + +All enabled custom actions can then be triggered for a resource of the type the action is defined for or provided while running, using the **Run Action** view or runCustomAction API. + + |run-custom-action-instance.png| + + |run-custom-action.png| + + +.. Images + + +.. |add-custom-action.png| image:: /_static/images/add-custom-action.png +.. |run-custom-action-instance.png| image:: /_static/images/run-custom-action-instance.png +.. |run-custom-action.png| image:: /_static/images/run-custom-action.png diff --git a/source/adminguide/extensions/developer.rst b/source/adminguide/extensions/developer.rst new file mode 100644 index 0000000000..cd9bc976b4 --- /dev/null +++ b/source/adminguide/extensions/developer.rst @@ -0,0 +1,240 @@ +.. 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. + +Writing Extensions for CloudStack +================================= + +The CloudStack Extensions Framework allows developers and operators to write extensions using any programming language or script. From CloudStack’s perspective, an extension is simply an executable capable of handling specific actions and processing input payloads. CloudStack invokes the executable by passing the action name and the path to a JSON-formatted payload file as command-line arguments. The extension processes the payload, performs the required operations on an external system, and returns the result as a JSON response written to `stdout`. + + +Create a New Extension +^^^^^^^^^^^^^^^^^^^^^^ + +You must first register a new extension using the API or UI: + +.. code-block:: bash + + cloudmonkey createExtension name=myext path=myext-executable + +Arguments: + +- ``name``: Unique name +- ``path``: Relative path to the executable. Root path will be `/usr/share/cloudstack-management/extensions/` + +The path must be: + +- Executable (``chmod +x``) +- Owned by the ``cloud:cloud`` user +- Present on all management servers (identical path and binary) + +If no explicit path is provided during extension creation, CloudStack will scaffold a basic shell script at a default location with minimal required action handlers. This provides a starting point for customization and ensures the extension is immediately recognized and callable by the system. + +CloudStack checks extension readiness periodically and shows its state in the UI/API. + +Extension Structure +^^^^^^^^^^^^^^^^^^^ + +Your extension must support the following invocation structure: + +.. code-block:: bash + + /path/to/executable + +Arguments: + +- ````: Action name (e.g., ``deploy``, ``start``, ``status``) +- ````: Path to the input JSON file +- ````: Max duration CloudStack will wait for completion + +Sample Invocation: + +.. code-block:: bash + + /usr/share/cloudstack-management/extensions/myext/myext.py deploy /var/lib/cloudstack/management/extensions/myext/162345.json 60 + +Input Format (Payload) +^^^^^^^^^^^^^^^^^^^^^^ + +CloudStack provides input via a JSON file, which your executable must read and parse. + +Example: + +.. code-block:: json + + { + "externaldetails": { + "resourcemap": { + ... + }, + "virtualmachine": { + "exttemplateid": "1" + }, + "host": { + ... + }, + "extension": { + ... + } + }, + "virtualmachineid": "...", + "cloudstack.vm.details": { + "id": 100, + "name": "i-2-100-VM", + ... + }, + "virtualmachinename": "i-2-100-VM", + "caller": { + "roleid": "6b86674b-7e61-11f0-ba77-1e00c8000158", + "rolename": "Root Admin", + "name": "admin", + "roletype": "Admin", + "id": "93567ed9-7e61-11f0-ba77-1e00c8000158", + "type": "ADMIN" + } + } + +The schema varies depending on the resource and action. Use this to perform context-specific logic. + +Output Format +^^^^^^^^^^^^^ + +Your extension should write a response JSON to ``stdout``. Example: + +.. code-block:: json + + { + "status": "success", + "message": "Deployment completed" + } + +For custom actions, CloudStack will display the ``message`` in the UI if the output JSON includes ``"printmessage": "true"``. +The ``message`` field can be a string, a JSON object or a JSON array. + +Action Lifecycle +^^^^^^^^^^^^^^^^ + +1. A CloudStack action (e.g., deploy VM) triggers a corresponding extension action. +2. CloudStack invokes the extension’s executable with appropriate parameters. +3. The extension processes the input and responds within the timeout. +4. CloudStack continues action workflow based on the result. + +Console Access for Instances with Orchestrator Extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Orchestrator extensions can provide console access for instances either through **VNC** or a **URL**. +To enable this, the extension must implement the ``getconsole`` action and return output in one of the following JSON formats: + +VNC-based console: + +.. code-block:: json + + { + "status": "success", + ... + "console": { + "host": "pve-node1.internal", + "port": "5901", + "password": "PVEVNC:6329C6AA::ZPcs5MT....d9", + "passwordonetimeuseonly": true + "protocol": "vnc" + } + } + +``passwordonetimeuseonly`` is optional. It can be set to ``true`` if the system returns a one-time-use VNC ticket. + +For VNC-based access, the returned details are forwarded to the Console Proxy VM (CPVM) in the same zone as the instance. The specified **host** and **port** must be reachable from the CPVM. + +Direct URL-based console: + +.. code-block:: json + + { + "status": "success", + ... + "console": { + "url": "CONSOLE_URL", + "protocol": "direct" + } + } + + +.. note:: + For URL–based console access, CloudStack does not report the acquired or client IP address. + In this mode, security and access control must be handled by the server providing the console. + + Protocol value of ``direct`` can be used for URL–based console access. + +Custom Actions +^^^^^^^^^^^^^^ + +You can define new custom actions for users or admin-triggered workflows. + +- Register via UI or ``addCustomAction`` API +- Define input parameters (name, type, required) +- Implement the handler for the custom action in your executable. + +CloudStack UI will render forms dynamically based on these definitions. + +Best Practices +^^^^^^^^^^^^^^ + +- Make executable/script idempotent and stateless +- Validate all inputs before acting +- Avoid hard dependencies on CloudStack internals +- Implement logging for troubleshooting +- Use exit code and ``stdout`` for signaling success/failure + +Extension Examples +^^^^^^^^^^^^^^^^^^ + +**Bash Example** + +.. code-block:: bash + + #!/bin/bash + ACTION=$1 + FILE=$2 + TIMEOUT=$3 + + if [ "$ACTION" == "deploy" ]; then + echo '{ "success": true, "result": { "message": "OK" } }' + else + echo '{ "success": false, "result": { "message": "Unsupported action" } }' + fi + +**Python Example** + +.. code-block:: python + + import sys, json + + action = sys.argv[1] + payload_file = sys.argv[2] + + with open(payload_file) as f: + data = json.load(f) + + if action == "deploy": + print(json.dumps({"success": True, "result": {"message": "Deployed"}})) + else: + print(json.dumps({"success": False, "result": {"message": "Unknown action"}})) + +For a clearer understanding of how to implement an extension, developers can refer to the base shell script scaffolded by CloudStack for orchestrator-type extensions. This script is located at: + +/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh + +It serves as a template with minimal required action handlers, making it a useful starting point for building new extensions. + +Additionally, CloudStack includes in-built extensions for Proxmox and Hyper-V that demonstrate how to implement extensions in different languages - Bash and Python. diff --git a/source/adminguide/extensions/inbuilt_extensions.rst b/source/adminguide/extensions/inbuilt_extensions.rst new file mode 100644 index 0000000000..d0641e2932 --- /dev/null +++ b/source/adminguide/extensions/inbuilt_extensions.rst @@ -0,0 +1,484 @@ +.. 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. + +In-built Orchestrator Extensions +================================ + +CloudStack provides in-built Orchestrator Extensions for Proxmox, Hyper-V and MaaS. These extensions work with Proxmox, Hyper-V and MaaS environments out of the box, and can also serve as reference implementations for anyone looking to develop new custom extensions. +The Extension files are located in `/usr/share/cloudstack-management/extensions/`, under the subdirectories `Proxmox`, `HyperV`, and `MaaS`. +The Proxmox Extension is written in shell script, while the Hyper-V and MaaS Extensions are written in python. +Proxmox and Hyper-V Extensions support some custom actions in addition to the standard VM actions like deploy, start, stop, reboot, status and delete. +After installing or upgrading CloudStack, in-built Extensions will show up in the Extensions section in UI. + + |built-in-extensions.png| + +**Note**: These Extensions may undergo changes with future CloudStack releases and backwards compatibility is not guaranteed. + +Proxmox +^^^^^^^^ + +The Proxmox CloudStack Extension is written in shell script and communicates with the Proxmox Cluster using the `Proxmox VE API `_ over HTTPS." + +Before using the Proxmox Extension, ensure that the Proxmox Datacenter is configured correctly and accessible to CloudStack. + +Since 4.22.0, console access support is available for instances deployed using the in-built Proxmox extension via VNC and console proxy VM. + +.. note:: + Proxmox VNC connections have a short initial connection timeout (about 10 seconds), + even when accessing the console from the CloudStack UI. If the noVNC interface takes + longer to load, or if there is a delay between creating the console endpoint and + opening it, the connection may fail on the first attempt. In such cases, users can + simply retry to establish the console session. + +Get the API Token-Secret from Proxmox +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If not already set up, create a new API Token in the Proxmox UI by navigating to `Datacenter > Permissions > API Tokens`. + +Uncheck the `Privilege Separation` checkbox in the `Add: Token` dialog + + |proxmox-add-token.png| + +Note down the **user**, **token**, and **secret**. + +Alternatively, check the `Privilege Separation` checkbox in the `Add: Token` dialog, and give permissions to the API Token +by navigating to `Datacenter > Permissions > Add > API Tokens Permission` + +- Set Role = `PVEAdmin` and Path = `/vms` +- Set Role = `PVEAdmin` and Path = `/storage` +- Set Role = `PVEAdmin` and Path = `/sdn` + + |proxmox-api-token-permission.png| + +To check whether the **token** and **secret** are working fine, you can check the following from the CloudStack Management Server: + +.. code-block:: bash + + export PVE_TOKEN='root@pam!=' + + curl -s -k -H "Authorization: PVEAPIToken=$PVE_TOKEN" https://:8006/api2/json/version | jq + +It should return a JSON response similar to this: + +.. code-block:: json + + { + "data": { + "repoid": "ec58e45e1bcdf2ac", + "version": "8.4.0", + "release": "8.4" + } + } + +Adding Proxmox to CloudStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To set up the Proxmox Extension, follow these steps in CloudStack: + +#. **Enable Extension** + + Enable the Extension by clicking the `Enable` button on the `Extensions` page in the UI. + +#. **Create Cluster** + + Create a Cluster with Hypervisor type `External` and Extension type `Proxmox`. + + |proxmox-add-cluster.png| + +#. **Add Host** + + Add a Host to the newly created Cluster with the following details: + + If the Proxmox nodes use a shared API endpoint or credentials, the `url`, `user`, `token`, and `secret` can be set in the Extension's `Configuration Details` instead of per Host. However, `node` and `network_bridge` must still be specified individually for each Host. + + * **url**: IP address/URL for Proxmox API access, e.g., `https://:8006`. + * **user**: User name for Proxmox API access + * **token**: API token for Proxmox + * **secret**: API secret for Proxmox + * **node**: Hostname of the Proxmox nodes + * **network_bridge**: Name of the network bridge to use for VM networking + + |proxmox-add-host.png| + + **Note**: If the TLS certificate cannot be verified when CloudStack connects to the Proxmox node, add the detail **verify_tls_certificate** and set it to **false** to skip certificate verification. + +#. **Create Template** + + A Template in CloudStack can map to either a `Template` or an `ISO` in Proxmox. + Provide a dummy `url` and template name. Select `External` as the hypervisor and `Proxmox` as the extension. Under `External Details`, specify: + + * **template_type**: `template` or `iso` + * **template_id**: ID of the template in Proxmox (if `template_type` is `template`) + + |proxmox-add-template.png| + + * **iso_path**: Full path to the ISO in Proxmox (if `template_type` is `iso`) + |proxmox-add-iso.png| + + Note: Templates and ISOs should be stored on shared storage when using multiple Proxmox nodes. Or copy the template/iso to each host's local storage at the same location. + +#. **Deploy Instance** + + Deploy an Instance using the Template created above. Optionally, provide the detail `vm_name` to specify the name of the VM in Proxmox. + Otherwise, the CloudStack Instance's internal name is used. The VM Id in Proxmox is mapped to the CloudStack Instance and stored as a detail in CloudStack DB. + The Instance will be provisioned on a randomly selected Proxmox host. The VM will be configured with the MAC address and VLAN ID as defined in CloudStack. + + |proxmox-deploy-instance.png| + +#. **Lifecycle Operations** + + Operations **Start**, **Stop**, **Reboot**, and **Delete** can be performed on the Instance from CloudStack. + +#. **Custom Actions** + + Custom actions **Create Snapshot**, **Restore Snapshot**, and **Delete Snapshot** are also supported for Instances. + +.. _proxmox-networking: +Configuring Networking +~~~~~~~~~~~~~~~~~~~~~~ + +Proxmox nodes and CloudStack hypervisor hosts must be connected via a VLAN trunked network. On each Proxmox node, +a bridge interface should be created and connected to the network interface that carries the VLAN-tagged traffic. +This bridge must be specified under Configuration Details (`network_bridge`) when registering the Proxmox node as a Host in CloudStack. + +When a VM is deployed, CloudStack includes the assigned MAC address and VLAN ID in the Extension payload. +The VM created on the Proxmox node is configured with this MAC and connected to the corresponding VLAN via the specified bridge. + +Upon boot, the VM broadcasts a VLAN-tagged DHCP request, which reaches the CloudStack Virtual Router (VR) handling that VLAN. +The VR responds with the appropriate IP address as configured in CloudStack. Once the VM receives the lease, it becomes fully integrated into the CloudStack-managed network. + +Users can then manage the Hyper-V VM like any other CloudStack guest Instance. Users can apply Egress Policies, +Firewall Rules, Port Forwarding, and other networking features seamlessly through the CloudStack UI or API. + +Hyper-V +^^^^^^ + +The Hyper-V CloudStack Extension is a Python-based script that communicates with the Hyper-V host using WinRM (Windows Remote Management) over HTTPS, +using NTLM authentication for secure remote execution of PowerShell commands that manage the full lifecycle of virtual machines. + +Each Hyper-V host maps to a CloudStack Host. Before using the Hyper-V Extension, ensure that the Hyper-V host is accessible to the CloudStack Management Server via WinRM over HTTPS. + +Console access for instances deployed using the Hyper-V extension is not available out of the box. + +Configuring WinRM over HTTPS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Windows Remote Management (WinRM)** is a protocol developed by Microsoft for securely managing Windows machines remotely using **WS-Management (Web Services for Management)**. +It allows remote execution of PowerShell commands over HTTP or HTTPS and is widely used in automation tools such as **Ansible**, **Terraform**, and **Packer** for managing Windows infrastructure. + +To enable WinRM over HTTPS on the Hyper-V host, ensure the following: + +- WinRM is enabled and configured to listen on port 5986 (HTTPS). +- A valid TLS certificate is installed and bound to the WinRM listener. You may use a certificate from a trusted Certificate Authority (CA) or a self-signed certificate. +- The firewall on the Hyper-V host allows inbound connections on TCP port 5986. +- The CloudStack Management Server has network access to the Hyper-V host on port 5986. +- The Hyper-V host has a local or domain user account with appropriate permissions for managing virtual machines (e.g., creating, deleting, configuring VMs). + +Sample powershell script to configure WinRM over HTTPS with self-signed TLS certificate is given below: + +.. code-block:: powershell + + Enable-PSRemoting -Force + $cert = New-SelfSignedCertificate -DnsName "$env:COMPUTERNAME" -CertStoreLocation Cert:\LocalMachine\My + New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbprint $cert.Thumbprint -Force + New-NetFirewallRule -DisplayName "WinRM HTTPS" -Name "WinRM-HTTPS" -Protocol TCP -LocalPort 5986 -Direction Inbound -Action Allow + +Install pywinrm on CloudStack Management Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**pywinrm** is a Python library that acts as a client to remotely execute commands on Windows machines via the WinRM protocol. Install it using ``pip3 install pywinrm``. + +Host Details +~~~~~~~~~~~~ + +Apart from the `url`, `username` and `password`, the following details are required when adding a Hyper-V host in CloudStack: + +* **network_bridge**: Name of the network bridge to use for VM networking. This bridge must be configured on the Hyper-V host and connected to the appropriate network interface as explained in the `Configuring Networking` section below. +* **vhd_path**: Path to the storage location where VM disks will be created. +* **vm_path**: Path to the storage location where VM configuration files and metadata will be stored. +* **verify_tls_certificate**: Set to `false` to skip TLS certificate verification for self-signed certificates. + + +Adding Hyper-V to CloudStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. **Enable Extension** + + Enable the Extension by clicking the `Enable` button on the `Extensions` page in the UI. + +#. **Create Cluster** + + Create a Cluster with Hypervisor type `External` and Extension type `HyperV`. + + |hyperv-add-cluster.png| + +#. **Add Host** + + Add a Host to the newly created Cluster with the following details: + + |hyperv-add-host.png| + **Note**: Add the detail **verify_tls_certificate** set to **false** to skip TLS certificate verification for self-signed certificates. + +#. **Create Template** + + A Template in CloudStack can map to either a `Template` or an `ISO` in Hyper-V. + Provide a dummy `url` and Template name. Select `External` as the hypervisor and `HyperV` as the Extension. Under `External Details`, specify: + + * **template_type**: `template` or `iso` + * **generation**: VM generation (1 or 2) + * **template_path**: Full path to the template .vhdx file (if `template_type` is `template`) + + |hyperv-add-template.png| + + * **iso_path**: Full path to the ISO in HyperV (if `template_type` is `iso`) + * **vhd_size_gb**: Size of the VHD disk to create (in GB) (if `template_type` is `iso`) + + |hyperv-add-iso.png| + + Note: Templates and ISOs should be stored on shared storage when using multiple HyperV nodes. Or copy the template/iso to each host's local storage at the same location. + +#. **Deploy Instance** + + Deploy an Instance using the template created above. The Instance will be provisioned on a randomly selected Hyper-V host. + The VM will be configured with the MAC address and VLAN ID as defined in CloudStack. + The VM in Hyper-V is created with the name `'CloudStack Instance's internal name' + '-' + 'CloudStack Instance's UUID'` to keep it unique. + +#. **Lifecycle Operations** + + Operations **Start**, **Stop**, **Reboot**, and **Delete** can be performed on the Instance from CloudStack. + +#. **Custom Actions** + + Custom actions **Suspend**, **Resume**, **Create Snapshot**, **Restore Snapshot**, and **Delete Snapshot** are also supported for Instances. + +Configuring Networking +~~~~~~~~~~~~~~~~~~~~~~ + +Hyper-V hosts and CloudStack hypervisor Hosts must be connected via a VLAN trunked network. +On each Hyper-V host, an external virtual switch should be created and bound to the physical network interface that carries VLAN-tagged traffic. +This switch must be specified in the Configuration Details (network_bridge) when adding the Hyper-V host to CloudStack. + +When a VM is deployed, CloudStack includes the assigned MAC address and VLAN ID in the Extension payload. +The VM is then created on the Hyper-V host with this MAC address and attached to the specified external switch with the corresponding VLAN configured. + +Upon boot, the VM sends a VLAN-tagged DHCP request, which reaches the CloudStack Virtual Router (VR) responsible for that VLAN. +The VR responds with the correct IP address as configured in CloudStack. Once the VM receives the lease, it becomes fully integrated into the CloudStack-managed network. + +Users can then manage the Hyper-V VM like any other CloudStack guest Instance. Users can apply Egress Policies, +Firewall Rules, Port Forwarding, and other networking features seamlessly through the CloudStack UI or API. + +MaaS +^^^^ + +The MaaS Extension for CloudStack is written in Python and communicates with `Canonical MaaS `_ using the `MaaS APIs `_. + +Before using the MaaS Extension, ensure that the Canonical MaaS Service is configured correctly with servers added into it and accessible to CloudStack. + +Get the API key from MaaS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If not already set up, create a new API Key in the MaaS UI by navigating to left column under `admin > API keys`. + +Existing `MAAS consumer` token can be used or a new API key can be generated by clicking the `Generate MAAS API Key` button + + |MaaS-add-token.png| + +Note down the **key** value. + +You can verify the MAAS API key and connectivity from the CloudStack Management Server by using the MAAS CLI as shown below (replace the example values with your own): + +.. code-block:: bash + + maas login admin http://:5240/MAAS + + # Example: + maas login admin http://10.0.80.47:5240/MAAS QqeFTc4fvz9qQyPzGy:UUGKTDf6VwPVDnhXUp:wtAZk6rKeHrFLyDQD9sWcASPkZVSMu6a + + # Verify MAAS connectivity and list machines + maas admin machines read | jq '.[].system_id' + +If the connection is successful, the command will list all registered machine system IDs from MAAS. + +Install required Python libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MAAS Orchestrator Extension uses OAuth1 for API authentication. + +Ensure the required Python libraries are installed on the CloudStack Management Server before using this extension. +The following command is provided as an example, package installation steps may vary depending on the host operating system: + +.. code-block:: bash + + pip3 install requests requests_oauthlib + +Adding MaaS to CloudStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To set up the MaaS Extension, follow these steps in CloudStack: + +#. **Use Default Extension** + + A default MaaS Extension is already available and enabled under `Extensions` tab. + +#. **Create Cluster** + + Create a Cluster with Hypervisor type `External` and Extension type `MaaS`. + + |MaaS-add-cluster.png| + +#. **Add Host** + + Add a Host to the newly created Cluster with the following details: + + To access MaaS environment, the `endpoint`, `apikey` need to be set in the Host. + + * **endpoint**: IP address of the MaaS server. The API used for operations in the script will look like `http://:5240/MAAS/api/2.0`. + * **apikey**: API key for MaaS + + |MaaS-add-host.png| + + +#. **Create Template** + + A Template in CloudStack maps to an image available in MaaS that can be deployed on a baremetal server. + Provide a dummy `url` and template name. Select `External` as the hypervisor and `MaaS` as the extension. + Under `External Details`, specify the following parameters: + + * **os**: Operating system name (e.g., `ubuntu`) + * **distro_series**: Ubuntu codename (e.g., `focal`, `jammy`) + * **architecture**: Image architecture name as listed in MaaS (e.g., `amd64/ga-20.04`, `amd64/hwe-22.04`, `amd64/generic`) + + MAAS uses only distro_series to identify the operating system for Ubuntu-based images (for example, focal, jammy). + + Example configurations: + + .. code-block:: text + + # Ubuntu 20.04 (Focal) + os=ubuntu + distro_series=focal + architecture=amd64/ga-20.04 + + |MaaS-add-template.png| + +#. **Deploy Instance** + + Deploy an Instance using the Template created above. The Instance will be provisioned on a randomly selected MaaS machine. + **maas_system_id** value can be provided in the external details to deploy the instance on specific server. + + |MaaS-deploy-instance.png| + +#. **Lifecycle Operations** + + Operations **Start**, **Stop**, **Reboot**, and **Delete** can be performed on the Instance from CloudStack. + +Configuring Networking and additional details +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The MaaS scenarios have been tested and verified only with a Shared Network setup in CloudStack and with ubuntu based images, using the MAAS Orchestrator Extension. +Please find some additional notes with respect to the networking and access related configuration as below, + +#. **Configuring TFTP to point to MAAS** + + Ensure that the TFTP or PXE boot configuration (for example, in pfSense or your network’s DHCP server) is set to point to the MAAS server as the TFTP source. + This ensures that VMs retrieve boot images directly from MAAS during PXE boot. + +#. **Using CloudStack Virtual Router (VR) as an External DHCP Server** + + If the end user wants the **CloudStack Virtual Router (VR)** to act as the external DHCP server for instances provisioned through MAAS, the following configuration steps must be performed. + + **In CloudStack** + + a. Navigate to **Networks → Add Shared Network**. + b. Create a Shared Network using the **DefaultSharedNetworkOffering**, and define an appropriate **Guest IP range**. + + |CloudStack-shared-network.png| + + **In MAAS** + + a. Navigate to **Networking → Subnets → Add Subnet** and create a subnet corresponding to the same IP range used in CloudStack. + + |MaaS-add-subnet-1.png| + |MaaS-add-subnet-2.png| + + b. Once the subnet is added: + - Ensure **Managed allocation** is **disabled**. + - Ensure **Active discovery** is **enabled**. + + |MaaS-subnet-configuration.png| + + c. Add a **Reserved IP range** that matches the CloudStack Guest range (optional, for clarity). + + |MaaS-add-reserve-iprange.png| + + d. Disable the DHCP service in MAAS: + - Navigate to **Subnets → VLAN → Edit VLAN**. + - Ensure the **DHCP service** is **disabled**. + + |MaaS-disable-dhcp.png| + + e. For all the servers in MAAS, navigate to each server in the Ready state, go to Network → Server Interface → Edit Physical, and set the IP mode to DHCP. + + |MaaS-enable-dhcp-on-servers.png| + + This configuration allows the CloudStack Virtual Router (VR) to provide IP address allocation and DHCP services for the baremetal instances managed through MAAS. + +#. **Using CloudStack-Generated SSH Keys for Baremetal Access** + + If the user wants to use the **SSH key pair generated in CloudStack** to log into the baremetal server provisioned by MAAS, perform the following steps. + + **In CloudStack** + + a. Navigate to **Compute → SSH Keypairs → Create SSH Keypair**. + b. Save the generated **private key** for later use (CloudStack stores only the public key). + + **In MAAS** + + a. Navigate to **Admin → SSH Keys → Import**. + b. Paste the **public key** from the CloudStack-generated SSH key pair. + c. Save the changes. + + |MaaS-add-sshkeypair.png| + + + After these steps, any baremetal node deployed via the MAAS Extension can be accessed using the **private key** from CloudStack. + +.. Images + + +.. |built-in-extensions.png| image:: /_static/images/built-in-extensions.png +.. |proxmox-add-cluster.png| image:: /_static/images/proxmox-add-cluster.png +.. |proxmox-add-host.png| image:: /_static/images/proxmox-add-host.png +.. |proxmox-add-token.png| image:: /_static/images/proxmox-add-token.png +.. |proxmox-api-token-permission.png| image:: /_static/images/proxmox-api-token-permission.png +.. |proxmox-add-template.png| image:: /_static/images/proxmox-add-template.png +.. |proxmox-add-iso.png| image:: /_static/images/proxmox-add-iso.png +.. |proxmox-deploy-instance.png| image:: /_static/images/proxmox-deploy-instance.png +.. |hyperv-add-cluster.png| image:: /_static/images/hyperv-add-cluster.png +.. |hyperv-add-host.png| image:: /_static/images/hyperv-add-host.png +.. |hyperv-add-template.png| image:: /_static/images/hyperv-add-template.png +.. |hyperv-add-iso.png| image:: /_static/images/hyperv-add-iso.png +.. |MaaS-add-token.png| image:: /_static/images/MaaS-add-token.png +.. |MaaS-add-cluster.png| image:: /_static/images/MaaS-add-cluster.png +.. |MaaS-add-host.png| image:: /_static/images/MaaS-add-host.png +.. |MaaS-add-template.png| image:: /_static/images/MaaS-add-template.png +.. |MaaS-deploy-instance.png| image:: /_static/images/MaaS-deploy-instance.png +.. |CloudStack-shared-network.png| image:: /_static/images/CloudStack-shared-network.png +.. |MaaS-add-subnet-1.png| image:: /_static/images/MaaS-add-subnet-1.png +.. |MaaS-add-subnet-2.png| image:: /_static/images/MaaS-add-subnet-2.png +.. |MaaS-subnet-configuration.png| image:: /_static/images/MaaS-subnet-configuration.png +.. |MaaS-add-reserve-iprange.png| image:: /_static/images/MaaS-add-reserve-iprange.png +.. |MaaS-disable-dhcp.png| image:: /_static/images/MaaS-disable-dhcp.png +.. |MaaS-add-sshkeypair.png| image:: /_static/images/MaaS-add-sshkeypair.png +.. |MaaS-enable-dhcp-on-servers.png| image:: /_static/images/MaaS-enable-dhcp-on-servers.png \ No newline at end of file diff --git a/source/adminguide/extensions/limitations.rst b/source/adminguide/extensions/limitations.rst new file mode 100644 index 0000000000..d043565b79 --- /dev/null +++ b/source/adminguide/extensions/limitations.rst @@ -0,0 +1,53 @@ +.. 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. + + +Limitations +=========== + +Although the external Instances behave a lot like CloudStack managed +Instances in many ways, there are some limitations. Some of these +limitations are due to the framework itself, while others can be addressed +by adding custom actions in the scripts written for the built-in extensions. + +**Some general features/actions not supported at the framework level:** + + - Data volumes. + + - User Data and Metadata services. + + - SSH key injection. + + - Affinity Groups. + + - Migrate Instance. + + - Host Capacity and Utilization Stats. + + - Add Nics to Instance post deployment. + +**Actions which can be implemented using Custom Actions in built-in extensions:** + + - Reinstall Instance. + + - Backup and Restore. + + - Recurring Snapshots. + + - Change Service Offering. + + - Resize Volume. + + - Attach ISO. diff --git a/source/adminguide/extensions/troubleshooting.rst b/source/adminguide/extensions/troubleshooting.rst new file mode 100644 index 0000000000..815da5d352 --- /dev/null +++ b/source/adminguide/extensions/troubleshooting.rst @@ -0,0 +1,70 @@ +.. 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. + + +Troubleshooting Extensions +========================== + +Validate the Extension Path +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - Ensure that the path is correctly defined and accessible on all management servers. The executable must be owned by the `cloud` user and group, and have appropriate permissions to be executed by `cloud:cloud`. + + - The script or binary must be executable and have appropriate permissions. + + - If the binary differs across management servers, the extension will be marked as Not Ready. + + - Ensure files are stored at: `/usr/share/cloudstack-management/extensions/` + + - CloudStack runs a background task at regular intervals to verify path readiness. If the path is not ready, its state will appear as Not Ready in the UI or API responses. + + - Alerts are generated if the extension path is not ready. + + - The check interval can be configured using the global configuration - `extension.path.state.check.interval`. The default is 5 minutes. + +Verify Payload Handling +^^^^^^^^^^^^^^^^^^^^^^^ + + - Ensure the extension binary can correctly read and parse the incoming JSON payload. + + - Payload files are placed at: `/var/lib/cloudstack/management/extensions//` + + - These payload files are automatically cleaned up after 24 hours. + + - Improper parsing of the payload is a common cause of failure—log any parsing errors in your extension binary for debugging. + +Refer to Base Extension Scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - For guidance on implementing supported actions, refer to the base scripts present for each extension type. + + - For Orchestrator-type extensions, see: `/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh` + + - These scripts provide examples of how to handle standard actions like start, stop, status, etc. + +Check Logs for Errors +^^^^^^^^^^^^^^^^^^^^^ + + - If the extension does not respond or returns an error, check the management server logs. + + - Logs include details of: + + 1. Invocation of the extension binary + + 2. Payload hand-off + + 3. Output parsing + + - Any exceptions or exit code issues. diff --git a/source/adminguide/guest_os.rst b/source/adminguide/guest_os.rst new file mode 100644 index 0000000000..04b8ec1cb0 --- /dev/null +++ b/source/adminguide/guest_os.rst @@ -0,0 +1,128 @@ +.. 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. + + +.. |guest-os-categories.png| image:: /_static/images/guest-os-categories.png + :alt: Guest OS Categories + +.. |add-guest-os-category.png| image:: /_static/images/add-guest-os-category.png + :alt: Add Guest OS Category form + +.. |guest-os-button.png| image:: /_static/images/guest-os-button.png + :alt: Guest OS section + +.. |add-guest-os-button.png| image:: /_static/images/add-guest-os-button.png + :alt: Add guest OS button + +.. |view-guest-os-mappings-button.png| image:: /_static/images/view-guest-os-mappings-button.png + :alt: View guest OS mappings button + +.. |guest-os-mapping-button.png| image:: /_static/images/guest-os-mapping-button.png + :alt: Guest OS mapping button + +.. |add-guest-os-mapping-button.png| image:: /_static/images/add-guest-os-mapping-button.png + :alt: Add guest OS mapping button + +CloudStack provides administrators a good control to manage the guest operating systems for the +Instances. CloudStack maintains the list of guest operating systems that are supported +by the hypervisors and also provides a way for operators or admins to add new guest OSs based on the need. +For an operating system to be supported to CloudStack for the Instances, it has to be added in CloudStack +and also need to have a mapping with the actual operating system name supported by hypervisor. + +Under "Configuration" section there are sub-sections for guest operating system. + +Guest OS Categories +------------------- + +A list of existing categories for the guest operating systems are shown as +"Guest OS Categories" section. Operators can also add new guest operating +system categories from the view. + +|guest-os-categories.png| + +Guest operating system categories are useful for categorizing images, i.e., +templates and ISOs, in several UI forms such as deploying an instance, +reinstalling an instance, etc., when the modern image selection is used in the +UI configuration. + +To allow a guest operating system category to be displayed in the UI forms, it +must be marked as featured. The order of the categories can also be controlled +using the Order option in the categories view. + +Like other resources, a custom resource icon can be set for a particular guest +operating system category for further control. If no resource icon is set for +a category, the UI will display default icons based on the category +name. + +An existing guest OS category can be deleted if it does not have any +associated guest operating systems. + +The "Add guest OS category" option allows operators to create new categories, +which can be marked as featured if they are meant to be displayed in the UI +forms. + +|add-guest-os-category.png| + +Guest OS +-------- + +A list of supported guest operating systems are shown under |guest-os-button.png| and also one can add new operating systems. + +To add a new guest OS, click on the button |add-guest-os-button.png| and following details needs to be provided: + +- **OS name** : Name of the operating system which will be displayed to the users. + +- **OS category** : Category of the operating system to which it belongs, eg. Windows, CentOS, Debian, etc. + +.. image:: /_static/images/add-guest-os-form.png + :width: 400px + :align: center + :alt: Guest OS dialog box + +Operator also need to add mapping with the actual operating system name supported by hypervisor as below. + +Guest OS hypervisor mapping +---------------------------- +Existing mappings are shown here and also one can add new mapping to an operating system. +To view the mappings of an existing guest OS click on |view-guest-os-mappings-button.png| under guest OS details. + +.. image:: /_static/images/guest-os-details-form.png + :width: 400px + :align: center + :alt: Guest OS details form + +To a new mapping, inside the sub-section |guest-os-mapping-button.png| click on |add-guest-os-mapping-button.png| +and following details needs to be provided. + +- **OS type** : Select the operating system type to which mapping needs to be created. + +- **Hypervisor** : Name of the hypervisor. + +- **Hypervisor version** : Specific version of the hypervisor. The exact version number found from hypervisor capabilities list. + +- **Hypervisor mapping name** : Name of the operating system specific to the hypervisor. Eg. For CentOS 5.0 (64-bit) in VMware + the specific name is "centos64Guest". + +- **Check OS name with hypervisor** : A toggle button to specify whether to verify the hypervisor mapping name with available + hypervisor. + +- **Force** : A toggle button to force add a user defined guest os mapping, overrides any existing user defined mapping. + +.. image:: /_static/images/guest-os-mapping-form.png + :width: 400px + :align: center + :alt: Guest OS mapping form + +Operator can also do operations like edit and delete guest OS and its hypervisor mappings. diff --git a/source/adminguide/host_and_storage_tags.rst b/source/adminguide/host_and_storage_tags.rst new file mode 100644 index 0000000000..211a83ea3d --- /dev/null +++ b/source/adminguide/host_and_storage_tags.rst @@ -0,0 +1,196 @@ +.. 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. + + +Host and Storage Tags +====================== + +Host tags and storage tags, despite the name, are not related to resource tags ( see section :ref:`resource-tags` ); they are a feature to direct resource allocation, such as which host the VM will be deployed on or which storage the volume will be created on. There are several reasons for using tags (such as directing the volume to better quality storage, according to the offering). + +Host tags +--------- +Host tags are responsible for directing VMs to compatible hosts. They are validated with the host tags informed in the compute offerings or in the system offerings. + +There are two types of host tags: + +- (Explicit) host tags: the host tags are managed by CloudStack, including the flexible host tags. Cloud operator can set, update, and delete host tags via CloudStack API or GUI. +- Implicit host tags: the host tags are not managed by CloudStack API. For more information, see section `“Implicit host tags” `_. + +To explain the behavior of host tags, some examples will be demonstrated with two hosts (Host1 and Host2): + +#. Tag setup: + + * Host1: h1 + * Host2: h2 + * Offering: h1 + + When a VM is created with the offering, the deployment will be carried out on Host1, as it is the one that has the tag compatible with the offering. + +#. Tag setup: + + * Host1: h1 + * Host2: h2,h3 + * Offering: h3 + + Hosts and offerings accept a list of tags, with comma (,) being their separator. So in this example, Host2 has the h2 and h3 tags. When a VM is created with the offering, the deployment will be carried out on Host2, as it is the one that has the tag compatible with the offering. + +#. Tag setup: + + * Host1: h1 + * Host2: h2,h3 + * Offering: (no tag) + + When the offering does not have tags, it will be possible to deploy the VM on any host. + +#. Tag setup: + + * Host1: (no tag) + * Host2: h2 + * Offering: h3 + + None of the hosts have compatible tags and it will not be possible to deploy a VM with the offering. However, CloudStack ignores this behavior when a host is manually selected. + +.. _strict-host-tags: + +Strict Host Tags +----------------- +During certain operations, such as changing the compute offering or starting or +live migrating an instance to a specific host, CloudStack may ignore the host +tags. This behavior is intentional and is designed to provide flexibility in +resource allocation. However, in some cases, this can lead to instances being +deployed on undesired hosts. + +To address this, CloudStack introduces an add-on feature that allows administrators +to enforce tag checks during these operations. By specifying the required tags +in the global configuration `vm.strict.host.tags`, CloudStack will ensure that +the specified tags must match during the operations. If any of the specified +tags do not match, the operation will fail. + +If `resource.limit.host.tags` are defined and +`vm.strict.resource.limit.host.tag.check` is set to true, the tags defined in +`resource.limit.host.tags` are included with the `vm.strict.host.tags`. + +.. list-table:: Strict host tags related global settings + :header-rows: 1 + + * - Parameter + - Default + - Description + * - ``vm.strict.host.tags`` + - empty + - A comma-separated list of tags which must match during operations like + modifying the compute offering for an instance, and starting or live + migrating an instance to a specific host. + * - ``vm.strict.resource.limit.host.tag.check`` + - `true` + - If set to true, tags specified in `resource.limit.host.tags` are also + included in `vm.strict.host.tags`. + +Storage tags +------------ +Storage tags are responsible for directing volumes to compatible primary storage. They are validated with the storage tags entered in the disk offerings or system offerings. + +To explain the behavior of storage tags, some examples will be demonstrated: + +#. Tag setup: + + * Storage: A + * Offering: A,B + + Storage and offering accept a list of tags, with the comma (,) being their separator. Therefore, in this example, the offering has tags A and B. In this example, it will not be possible to allocate the volume, as all the offering tags must exist in the storage. Although the storage has the A tag, it does not have the B tag. + +#. Tag setup: + + * Storage: A,B,C,D,X + * Offering: A,B,C + + In this example, it will be possible to allocate the volume, as all the offering tags exist in the storage. + +#. Tag setup: + + * Storage: A, B, C + * Offering: (no tag) + + In this example, it will be possible to allocate the volume, as the offering does not have any tag requirements. + +#. Tag setup: + + * Storage: (no tag) + * Offering: D,E + + In this example, it will not be possible to allocate the volume, as the storage does not have tags, therefore it does not meet the offering requirements. + +In short, if the offering has tags, the storage will need to have all the tags for the volume to be allocated. If the offering does not have tags, the volume can be allocated, regardless of whether the storage has a tag or not. + +Flexible Tags +------------- +When defining tags for a resource (a host, for example), offerings with those tags will be directed to that resource. However, offerings without tags can also be targeted to it. So, even after adding tags to a resource with the intention of making it exclusive to certain types of offerings, this exclusivity can be ignored. + +Furthermore, the standard tag system only allows the user to enter a simple list of tags, without the possibility of creating more complex rules, such as checking whether the offering has certain pairs of tags. + +To overcome these situations, ACS allows hosts and storages to have tags that are rules written in JavaScript, also known as flexible tags. With flexible tags, the role of tag targeting is reversed, that is, instead of the host or storage needing to have the offering's tag for targeting to be carried out, the offering will need to have the tag of the resource to which it will be directed. This inversion means that offerings without tags cannot be directed to any resource. This way, operators can have finer control over the targeting of VMs and volumes within the environment. + +Configuring flexible tags on hosts is carried out through the ``updateHost`` API, entering the rule in the ``hosttags`` field. On the other hand, configuring flexible tags in the storages is done using the ``updateStoragePool`` API, informing the rule in the ``tags`` field. For the informed tag to be effectively interpreted as JavaScript, you must declare the ``istagarule`` parameter as true whenever you use one of the APIs presented. + +It is worth mentioning that the compute offering or disk offering tags are injected in list format. Thus, when validating an offering with tags ``A, B``, during processing, there will be the variable ``tags``, where ``tags[0]`` will be tag A, and ``tags[1]`` will be tag B. The order of the tags is significant and can affect the outcome, depending on how they are implemented. + +Example: tags[0] == "slow" || tags[1] == "fast" + Tags and results: + +- “slow,fast” -> TRUE +- “fast,slow” -> FALSE +- “fast” -> FALSE + +If you want to avoid dependency on tag order, use the following approach: + +Example: tags.indexOf('slow') >= 0 || tags.indexOf('fast') >= 0 + Tags and results: + +- “slow,fast” -> TRUE +- “fast,slow” -> TRUE +- “fast” -> TRUE + + +It's also important to mention that flexible tags are not compatible with quota's activation rules. + +Implicit Host Tags +------------------ +In Apache CloudStack 4.19 and prior, cloud operators are only able to set tags of host via Cloudstack API or on CloudStack GUI. + +Implicit host tags feature is supported since Apache CloudStack 4.20. With the feature, Cloud operators can easily set the +implicit host tags per host based on the server configurations. For example, based on the following hardware devices and +software which can be fetched by commands, scripts or tools: + +- CPU architecture and model +- Network card type and speed +- Hard disk type and raid type +- GPU model +- OS distribution and version + +To set it, please add the following line to /etc/cloudstack/agent/agent.properties and restart cloudstack-agent. + +.. parsed-literal:: + host.tags= + +Cloud operators can also get the information and set the implicit host tags by automation tools (chef, ansible, puppet, etc). + +.. note:: + - Implicit host tags are only configurable on KVM hosts. They are not managed by CloudStack API. + + - Implicit host tags are not compatible with flexible host tags. + + - Flexible host tags and host tags managed by CloudStack API are explicit tags. + + - Explicit and implicit host tags have no difference in VM instance deployment and migration. diff --git a/source/adminguide/hosts.rst b/source/adminguide/hosts.rst index 9a593fddf9..b7c6b8df43 100644 --- a/source/adminguide/hosts.rst +++ b/source/adminguide/hosts.rst @@ -18,15 +18,15 @@ Adding Hosts ------------ Additional hosts can be added at any time to provide more capacity for -guest VMs. For requirements and instructions, see :ref:`adding-a-host`. +guest Instances. For requirements and instructions, see :ref:`adding-a-host`. Scheduled Maintenance and Maintenance Mode for Hosts ---------------------------------------------------- You can place a host into maintenance mode. When maintenance mode is -activated, the host becomes unavailable to receive new guest VMs, and -the guest VMs already running on the host are seamlessly migrated to +activated, the host becomes unavailable to receive new guest Instances, and +the guest Instances already running on the host are seamlessly migrated to another host not in maintenance mode. This migration uses live migration technology and does not interrupt the execution of the guest. @@ -39,13 +39,13 @@ must be used in concert. CloudStack and vCenter have separate maintenance modes that work closely together. #. Place the host into CloudStack's "scheduled maintenance" mode. This - does not invoke the vCenter maintenance mode, but only causes VMs to + does not invoke the vCenter maintenance mode, but only causes Instances to be migrated off the host When the CloudStack maintenance mode is requested, the host first moves into the Prepare for Maintenance state. In this state it cannot - be the target of new guest VM starts. Then all VMs will be migrated - off the server. Live migration will be used to move VMs off the host. + be the target of new guest Instance starts. Then all Instances will be migrated + off the server. Live migration will be used to move Instances off the host. This allows the guests to be migrated to other hosts with no disruption to the guests. After this migration is completed, the host will enter the Ready for Maintenance mode. @@ -53,7 +53,7 @@ maintenance modes that work closely together. #. Wait for the "Ready for Maintenance" indicator to appear in the UI. #. Now use vCenter to perform whatever actions are necessary to maintain - the host. During this time, the host cannot be the target of new VM + the host. During this time, the host cannot be the target of new Instance allocations. #. When the maintenance tasks are complete, take the host out of @@ -66,8 +66,8 @@ maintenance modes that work closely together. #. Then use CloudStack's administrator UI to cancel the CloudStack maintenance mode - When the host comes back online, the VMs that were migrated off of - it may be migrated back to it manually and new VMs can be added. + When the host comes back online, the Instances that were migrated off of + it may be migrated back to it manually and new Instances can be added. XenServer and Maintenance Mode @@ -75,10 +75,10 @@ XenServer and Maintenance Mode For XenServer, you can take a server offline temporarily by using the Maintenance Mode feature in XenCenter. When you place a server into -Maintenance Mode, all running VMs are automatically migrated from it to +Maintenance Mode, all running Instances are automatically migrated from it to another host in the same pool. If the server is the pool master, a new master will also be selected for the pool. While a server is Maintenance -Mode, you cannot create or start any VMs on it. +Mode, you cannot create or start any Instances on it. **To place a server in Maintenance Mode:** @@ -92,7 +92,7 @@ Mode, you cannot create or start any VMs on it. #. Click Enter Maintenance Mode. -The server's status in the Resources pane shows when all running VMs +The server's status in the Resources pane shows when all running Instances have been successfully migrated off the server. **To take a server out of Maintenance Mode:** @@ -152,7 +152,7 @@ Removing XenServer and KVM Hosts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A node cannot be removed from a cluster until it has been placed in -maintenance mode. This will ensure that all of the VMs on it have been +maintenance mode. This will ensure that all of the Instances on it have been migrated to other Hosts. To remove a Host from the cloud: #. Place the node in maintenance mode. @@ -164,7 +164,7 @@ migrated to other Hosts. To remove a Host from the cloud: #. Use the UI option to remove the node. - Then you may power down the Host, re-use its IP address, re-install + Then you may power down the Host, reuse its IP address, re-install it, etc @@ -200,7 +200,7 @@ hypervisor patches. The hypervisor vendor is likely to refuse to support any system that is not up to date with patches. .. note:: - The lack of up-do-date hotfixes can lead to data corruption and lost VMs. + The lack of up-do-date hotfixes can lead to data corruption and lost Instances. (XenServer) For more information, see `Highly Recommended Hotfixes for XenServer in the CloudStack Knowledge Base @@ -209,7 +209,7 @@ any system that is not up to date with patches. Hypervisor Capabilities ----------------------- -For different hypervisors and their versions, various capabilities such as maximum number of guest VMs per host, maximum number of volumes per VM, security group support, etc are considered by CloudStack. These capabilities are stored in the **cloud.hypervisor_capabilities** table in the database. If a specific hypervisor version is not available in the database, values against the *default* version for the hypervisor will be used. +For different hypervisors and their versions, various capabilities such as maximum number of guest Instances per host, maximum number of volumes per Instance, security group support, etc are considered by CloudStack. These capabilities are stored in the **cloud.hypervisor_capabilities** table in the database. If a specific hypervisor version is not available in the database, values against the *default* version for the hypervisor will be used. These capabilities can be listed using API - ``listHypervisorCapabilities``. Some of the hypervisor capabilities can also be updated for a hypervisor type and version combination using API - ``updateHypervisorCapabilities``. Following hypervisor-specific documentations can be referred for different maximums for a particular hypervisor host: @@ -220,9 +220,65 @@ Following hypervisor-specific documentations can be referred for different maxim .. note:: - Guest VM limit check is not done while deploying a VM on a KVM hypervisor host. + Guest Instance limit check is not done while deploying an Instance on a KVM hypervisor host. +.. _discovering-gpu-devices-on-kvm-hosts: + +Discovering GPU Devices on KVM Hosts +-------------------------------- + +For KVM, the user needs to ensure that IOMMU is enabled and the necessary +drivers are installed. If vGPU is to be used, the user needs to ensure that +the vGPU type is supported by the host and has been created on the host. The +cloudstack agent uses the ``gpudiscovery.sh`` script to discover the GPU devices +on the host. For more information on how to prepare the host for GPU +passthrough, see `Managing GPU devices in virtual machines `_. + +Once the host is configured with the GPU devices, the operator can trigger the +discovery of the GPU devices on the host by using ``discoverGPUdevices`` command +using cmk or use the ``Discover GPU devices`` button on the host details page in the UI. +This triggers a request to the cloudstack agent to discover the GPU devices on +the host. + +The cloudstack agent uses the ``gpudiscovery.sh`` script to discover the GPU +devices on a KVM host. The script is located in the +``/usr/share/cloudstack-common/scripts/vm/kvm/`` directory on the host. The script +relies on the ``lspci`` & ``xmlstarlet`` command to discover the GPU devices +and their status on the host. So, for the discovery to be successful, the +``lspci`` & ``xmlstarlet`` should be installed on the host. + + .. parsed-literal:: + + dnf install pciutils xmlstarlet + + .. parsed-literal:: + + sudo apt install pciutils xmlstarlet + +.. note:: + The following table shows the compatibility matrix for NVIDIA vGPU types with CloudStack: + + .. cssclass:: table-striped table-bordered table-hover + + =============================== ================== ======================= + NVIDIA vGPU Type VFIO Framework Supported in CloudStack + =============================== ================== ======================= + Legacy: SR-IOV not supported `mdev` Yes + SR-IOV supported `mdev` Yes + SR-IOV supported `Vendor specific` Yes + Multi Instance GPU No + =============================== ================== ======================= + + The script can also be run manually to debug the discovery of the GPU devices on a host. + + .. parsed-literal:: + + sudo /usr/share/cloudstack-common/scripts/vm/kvm/gpudiscovery.sh + + The script will output the GPU devices in a JSON found on the host. The operator + can also update the script to customize the discovery of the GPU devices on the host. + Changing Host Password ---------------------- @@ -244,11 +300,10 @@ To change a Node's password: .. code:: bash - java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.0.jar \ - org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \ - encrypt.sh input="newrootpassword" \ - password="databasekey" \ - verbose=false + java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar \ + com.cloud.utils.crypt.EncryptionCLI \ + -p databasekey \ + -i newrootpassword #. Get the list of host IDs for the host in the cluster where you are changing the password. You will need to access the database to @@ -281,7 +336,7 @@ Over-Provisioning and Service Offering Limits (Supported for XenServer, KVM, and VMware) CPU and memory (RAM) over-provisioning factors can be set for each -cluster to change the number of VMs that can run on each host in the +cluster to change the number of Instances that can run on each host in the cluster. This helps optimize the use of resources. By increasing the over-provisioning factor, more resource capacity will be used. If the factor is set to 1, no over-provisioning is done. @@ -298,7 +353,7 @@ Capacity = 2 GB Over-provisioning factor = 2 Capacity after over-provisioning = 4 GB -With this configuration, suppose you deploy 3 VMs of 1 GB each: +With this configuration, suppose you deploy 3 Instances of 1 GB each: Used = 3 GB Free = 1 GB @@ -307,14 +362,14 @@ The administrator can specify a memory over-provisioning factor, and can specify both CPU and memory over-provisioning factors on a per-cluster basis. -In any given cloud, the optimum number of VMs for each host is affected +In any given cloud, the optimum number of Instances for each host is affected by such things as the hypervisor, storage, and hardware configuration. These may be different for each cluster in the same cloud. A single global over-provisioning setting can not provide the best utilization for all the different clusters in the cloud. It has to be set for the lowest common denominator. The per-cluster setting provides a finer granularity for better utilization of resources, no matter where the -CloudStack placement algorithm decides to place a VM. +CloudStack placement algorithm decides to place an Instance. The overprovisioning settings can be used along with dedicated resources (assigning a specific cluster to an account) to effectively offer @@ -336,9 +391,9 @@ Limitations on Over-Provisioning in XenServer and KVM - In XenServer, due to a constraint of this hypervisor, you can not use an over-provisioning factor greater than 4. -- The KVM hypervisor can not manage memory allocation to VMs +- The KVM hypervisor can not manage memory allocation to Instances dynamically. CloudStack sets the minimum and maximum amount of memory - that a VM can use. The hypervisor adjusts the memory within the set + that an Instance can use. The hypervisor adjusts the memory within the set limits based on the memory contention. @@ -354,33 +409,34 @@ responsibility to ensure that these requirements are met. Balloon Driver ^^^^^^^^^^^^^^ -All VMs should have a balloon driver installed in them. The hypervisor +All Instances should have a balloon driver installed in them. The hypervisor communicates with the balloon driver to free up and make the memory -available to a VM. +available to an Instance. XenServer ''''''''' The balloon driver can be found as a part of xen pv or PVHVM drivers. -The xen pvhvm drivers are included in upstream linux kernels 2.6.36+. +The xen PVHVM drivers are included in upstream linux kernels 2.6.36+. VMware '''''' The balloon driver can be found as a part of the VMware tools. All the -VMs that are deployed in a over-provisioned cluster should have the +Instances that are deployed in a over-provisioned cluster should have the VMware tools installed. KVM ''' -All VMs are required to support the virtio drivers. These drivers are +All KVM Instances are required to support the virtio drivers. These drivers are installed in all Linux kernel versions 2.6.25 and greater. The administrator must set CONFIG\_VIRTIO\_BALLOON=y in the virtio -configuration. +configuration. Drivers for Windows can be downloaded from +https://github.com/virtio-win/virtio-win-pkg-scripts Hypervisor capability @@ -396,12 +452,45 @@ The DMC (Dynamic Memory Control) capability of the hypervisor should be enabled. Only XenServer Advanced and above versions have this feature. -VMware, KVM -''''''''''' +VMware +'''''' Memory ballooning is supported by default. +KVM +''' + +Memory ballooning is supported and enabled by default. This can be configured on +per KVM host basis via the `vm.memballoon.disable=false` property and the +`vm.memballoon.stats.period` property in the `agent.properties` of the KVM host. + +The memory ballooning feature on KVM allows the host to reclaim memory from +guest VMs which is enabled by a virtio balloon device on the guest VM and the +related virtio drivers inside the guest VMs. This feature is mainly intended to +support over-committing memory on KVM hosts. + +A related feature, KSM (Kernel Same-page Merging), can also be enabled to assist +with over-committing memory. On some distributions such as Ubuntu, this is +enabled by default, and can be checked otherwise by checking/setting +`/sys/kernel/mm/ksm/run` to 1 and for libvirt set the `KSM_ENABLED=AUTO` in +`/etc/defaults/qemu-kvm`. + +Note: the memory ballooning feature isn't automatic on KVM and shouldn't be +confused with the dynamic scaling feature that allows manual scaling of running +Instances by changing the service offering (feature can be enabled via the setting +enable.dynamic.scale.vm) of Instances that aren't using a fixed compute offering. + +By default, when memory is over provisioned (setting mem.overprovisioning.factor +is greater than 1.0 at global or cluster level) the actual memory for the Instance is +the memory per the service offering divided by the global or cluster-specific +memory overprovisioning factor. This means guests start with a lower memory than +their service offering intended memory, which will not be changed or scaled +automatically. When overcommitting memory, this behaviour can be disabled by +turning off (set the value false) the setting +`vm.min.memory.equals.memory.divided.by.mem.overprovisioning.factor`. + + Setting Over-Provisioning Factors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -411,19 +500,19 @@ cpu.overprovisioning.factor and mem.overprovisioning.factor will be applied when a new cluster is created. Later, the factors can be modified for an existing cluster. -Only VMs deployed after the change are affected by the new setting. If -you want VMs deployed before the change to adopt the new -over-provisioning factor, you must stop and restart the VMs. When this is +Only Instances deployed after the change are affected by the new setting. If +you want Instances deployed before the change to adopt the new +over-provisioning factor, you must stop and restart the Instances. When this is done, CloudStack recalculates or scales the used and reserved capacities based on the new over-provisioning factors, to ensure that CloudStack is correctly tracking the amount of free capacity. .. note:: - It is safer not to deploy additional new VMs while the capacity + It is safer not to deploy additional new Instances while the capacity recalculation is underway, in case the new values for available - capacity are not high enough to accommodate the new VMs. Just wait + capacity are not high enough to accommodate the new Instances. Just wait for the new used/available values to become available, to be sure - there is room for all the new VMs you want. + there is room for all the new Instances you want. To change the over-provisioning factors for an existing cluster: @@ -439,7 +528,7 @@ To change the over-provisioning factors for an existing cluster: #. Fill in your desired over-provisioning multipliers in the fields CPU overcommit factor and RAM overcommit factor. The value which is - intially shown in these fields is the default value inherited from + initially shown in these fields is the default value inherited from the global configuration settings. .. note:: @@ -465,7 +554,7 @@ weight is based on the clock speed in the service offering. Guests receive a CPU allocation that is proportionate to the GHz in the service offering. For example, a guest created from a 2 GHz service offering will receive twice the CPU allocation as a guest created from a 1 GHz -service offering. CloudStack does not perform memory over-provisioning. +service offering. VLAN Provisioning @@ -562,7 +651,7 @@ The former behaviour also is supported — VLAN is randomly allocated to a network from the VNET range of the physical network when the network turns to Implemented state. The VLAN is released back to the VNET pool when the network shuts down as a part of the Network Garbage Collection. -The VLAN can be re-used either by the same network when it is +The VLAN can be reused either by the same network when it is implemented again, or by any other network. On each subsequent implementation of a network, a new VLAN can be assigned. @@ -643,7 +732,7 @@ management server(s). The ``outofbandmanagement.sync.poolsize`` is the maximum number of ipmitool background power state scanners that can run at a time. Based on the maximum number of hosts you've, you can increase/decrease the value depending on how much -stress your management server host can endure. It will take atmost number of +stress your management server host can endure. It will take at most number of total out-of-band-management enabled hosts in a round * ``outofbandmanagement.action.timeout`` / ``outofbandmanagement.sync.poolsize`` seconds to complete a background power-state sync scan in a single round. @@ -670,7 +759,7 @@ power management actions but in the UI a warning is displayed. Security -------- -Starting 4.11, CloudStack has an inbuilt certicate authority (CA) framework and +Starting 4.11, CloudStack has an inbuilt certificate authority (CA) framework and a default 'root' CA provider which acts as a self-signed CA. The CA framework participates in certificate issuance, renewal, revocation, and propagation of certificates during setup of a host. This framework is primary used to @@ -681,9 +770,9 @@ Following are some global settings that control various aspects of this feature. .. cssclass:: table-striped table-bordered table-hover -======================================= ==================================================================== +======================================= ==================================================================================================== Global setting Description -======================================= ==================================================================== +======================================= ==================================================================================================== ca.framework.provider.plugin The configured CA provider plugin ca.framework.cert.keysize The key size used for certificate generation ca.framework.cert.signature.algorithm The certificate signature algorithm @@ -691,13 +780,15 @@ ca.framework.cert.validity.period Certificate validity in days ca.framework.cert.automatic.renewal Whether to auto-renew expiring certificate on hosts ca.framework.background.task.delay The delay between each CA background task round in seconds ca.framework.cert.expiry.alert.period The number of days to check and alert expiring certificates -ca.plugin.root.private.key (hidden/encrypted in database) Auto-generated CA private key -ca.plugin.root.public.key (hidden/encrypted in database) CA public key -ca.plugin.root.ca.certificate (hidden/encrypted in database) CA certificate -ca.plugin.root.issuer.dn The CA issue distinguished name used by the root CA provider +ca.plugin.root.private.key (hidden) CA private key. Auto-generated if empty. PKCS#8 format required +ca.plugin.root.public.key (hidden) CA public key. Auto-generated if empty. X.509/SPKI format required +ca.plugin.root.ca.certificate (hidden) CA certificate chain. Auto-generated if empty. Supports intermediate CA chains +ca.plugin.root.issuer.dn The CA issuer distinguished name used by the root CA provider ca.plugin.root.auth.strictness Setting to enforce two-way SSL authentication and trust validation ca.plugin.root.allow.expired.cert Setting to allow clients with expired certificates -======================================= ==================================================================== +ca.framework.inject.default.truststore Injects CA certificate into JVM default truststore on startup for outgoing HTTPS trust + (default: ``true``). Restart management server(s) when changed +======================================= ==================================================================================================== A change in ``ca.framework.background.task.delay`` settings requires restarting of management server(s) as the thread pool and a background tasks are configured @@ -717,6 +808,76 @@ enforce authentication and validation strictness by setting ``ca.plugin.root.auth.strictness`` to ``true`` and restarting the management server(s). +Custom CA Support +~~~~~~~~~~~~~~~~~~ + +The built-in ``root`` CA provider supports user-provided CA +material. When the ``ca.plugin.root.private.key``, +``ca.plugin.root.public.key``, and ``ca.plugin.root.ca.certificate`` +configuration keys are pre-populated, CloudStack uses the provided CA instead +of auto-generating one. All internal certificate provisioning (agents, +SystemVMs, management server keystores) automatically use the configured CA. + +Starting 4.23, this support was enhanced to include: + +- **Intermediate CA chains**: The ``ca.plugin.root.ca.certificate`` key can now + contain a PEM-concatenated chain of certificates. +- **Outgoing HTTPS trust**: The configured CA is injected into the management + server's default truststore (controlled by ``ca.framework.inject.default.truststore``) + and the SystemVM's truststore, allowing outgoing HTTPS connections to trust + servers using this CA. This enables SystemVMs to download templates and ISOs + from HTTPS servers whose certificates are signed by the configured CA. +- **Validation**: User-provided keys are validated on startup to prevent silent + overwriting of malformed keys. + +All three keys must be set together. If any key is missing or malformed, the CA +provider will log a warning, overwrite them with auto-generated keys, and +the user will need to update the global settings again with valid values. +The private key must be in PKCS#8 format and the public key must be explicitly +extracted. Use the following commands to prepare the CA material: + +.. code:: bash + + # Convert private key to PKCS#8 format (required) + openssl pkcs8 -topk8 -nocrypt -in ca.key -out ca-pkcs8.key + + # Extract the public key + openssl rsa -in ca.key -pubout -out ca.pub + + # For intermediate CAs, concatenate into a single PEM chain + cat intermediate.crt root.crt > ca-chain.crt + +.. note:: + When migrating from one CA to another on an existing environment, agents + holding certificates signed by the old CA will fail to connect after the + management server restarts with the new CA. Ensure + ``ca.plugin.root.auth.strictness`` is set to ``false`` to allow agents to + reconnect, then use ``provisionCertificate`` to re-provision each host and + SystemVM with certificates signed by the new CA. Alternatively, use forced + provisionin (see below) for hosts that cannot reconnect. + +Forced Certificate Provisioning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``provisionCertificate`` API accepts a ``forced`` parameter (default: +``false``). When set to ``true``, the management server provisions certificates +directly via SSH instead of the agent communication channel. This is required +when agents cannot connect to the management server — for example, after a CA +change when the agent's keystore trusts the old CA. + +For KVM hosts, forced provisioning connects via SSH using stored host +credentials, provisions the certificate, and restarts the ``cloudstack-agent`` +and ``libvirtd`` services. For SystemVMs, it routes commands through the +SystemVM's SSH access. + +.. code:: bash + + # Force re-provision a disconnected KVM host + cmk provision certificate hostid= reconnect=true forced=true + + # Force re-provision a disconnected SystemVM + cmk provision certificate hostid= reconnect=true forced=true + Server Address Usage -------------------- @@ -773,7 +934,7 @@ and space are replaced with ``~``: Starting 4.11.1, a KVM host is considered secured when it has its keystore and certificates setup for both the agent and libvirtd process. A secured host will -only allow and initiate TLS enabled live VM migration. This requires libvirtd +only allow and initiate TLS enabled live Instance migration. This requires libvirtd to listen on default port 16514, and the port to be allowed in the firewall rules. Certificate renewal (using the ``provisionCertificate`` API) will restart both the libvirtd process and agent after deploying new certificates. @@ -788,7 +949,7 @@ Feature Overview - This feature applies to KVM hosts. - KVM utilised under CloudStack uses the standard Libvirt hook script behaviour as outlined in the Libvirt documentation page `hooks`_. - During the install of the KVM CloudStack agent, the Libvirt hook script "/etc/libvirt/hooks/qemu", referred to as the qemu script hereafter is installed. -- This is a python script that carries out network management tasks every time a VM is started, stopped or migrated, as per the Libvirt hooks specification. +- This is a python script that carries out network management tasks every time an Instance is started, stopped or migrated, as per the Libvirt hooks specification. - Custom network configuration tasks can be done at the same time as the qemu script is called. - Since the tasks in question are user-specific, they cannot be included in the CloudStack-provided qemu script. @@ -814,7 +975,7 @@ Usage #. Sub-operation indication, or '-' if there is none. #. An extra argument string, or '-' if there is none. -- The operation argument is based on what actions KVM and Libvirt are carrying out on each VM: 'prepare', 'start', 'started', 'stopped', 'release', 'migrate', 'restore', 'reconnect', 'attach'. +- The operation argument is based on what actions KVM and Libvirt are carrying out on each Instance: 'prepare', 'start', 'started', 'stopped', 'release', 'migrate', 'restore', 'reconnect', 'attach'. - If an invalid operation argument is received, the qemu script will log the fact, not execute any custom scripts and exit. @@ -841,18 +1002,18 @@ Timeout Configuration #. Find the "timeoutSeconds" timeout setting. #. Change the 10 * 60 value to a preferred timeout value. For example 20 * 60, for a 20-minute timeout. -Custom Script Naming for a Specific VM Action -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- For a custom script that needs to be executed at the end of a specific VM action, do the following: +Custom Script Naming for a Specific Instance Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- For a custom script that needs to be executed at the end of a specific Instance action, do the following: #. Navigate to the custom script that needs to be executed for a specific action. #. Rename the file by prefixing to the filename the specific action name followed by an underscore. For example, if a custom script is named abc.sh, then prefix 'migrate' and an underscore to the name to become migrate_abc.sh. -Custom Script Naming for All VM Actions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Custom Script Naming for All Instance Actions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- For a custom script that needs to be executed at the end of all VM actions, do the following: +- For a custom script that needs to be executed at the end of all Instance actions, do the following: #. Navigate to the custom script that needs to be executed for all actions. #. Rename the file by prefixing 'all' to the filename, followed by an underscore. For example, if a custom script is named def.py, then prefix 'all' and an underscore to the name to become all_def.py. @@ -891,7 +1052,7 @@ 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. +#. Pre-Maintenance 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. @@ -1003,3 +1164,51 @@ The management server iterates through hosts in each cluster on the selected sco - 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. + + +KVM Auto Enable/Disable Hosts +----------------------------- + +The cluster configuration 'enable.kvm.host.auto.enable.disable' (disabled by default) allows CloudStack to auto-disable and auto-enable KVM hosts resource state based on customisable host/hypervisor health checks. + +KVM hosts health checks +~~~~~~~~~~~~~~~~~~~~~~~ + +For each KVM agent on the cluster, the property 'agent.health.check.script.path' must be added to the agent.properties file, indicating the path of an executable file/script for host health check. + +.. note:: The health script runs every 'ping.interval' seconds on a KVM host. + +.. note:: The health script will need execution permissions on a KVM host. + +Depending on the exit code of the health script, the KVM agent will report the management server with the following results: + +- The health check result is true, if the script is executed successfully and the exit code is 0 +- The health check result is false, if the script is executed successfully and the exit code is 1 +- The health check result is null, if + + - Script file is not specified, or + - Script file does not exist, or + - Script file is not accessible by the user of the cloudstack-agent process, or + - Script file is not executable, or + - There are errors when the script is executed (exit codes other than 0 or 1) + +Management Server actions based on health checks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The management server receives the health check results from the KVM agent, and takes the following actions: + +- If the host health check result is null, do nothing. +- If the host health check result is true, enable the host resource state if it is Disabled. +- If the host health check result is false, disable the host resource state if it is Enabled. + +On every automatic enable or disable event, the management server will send an alert to the admin and add an automatic annotation (comment) on the specific host. + +- If a host gets auto-disabled by a health check failure, then it can be auto-enabled when the health check succeeds. But if the host gets disabled by the admin, then it must not be auto-enabled when the health check succeeds (manual host disabling takes precedence over the auto-enabling of a host). +- If a host gets auto-disabled by a health check failure, the admin could enable the host but unless they also disable the health check on the host then it will just get disabled again when the health check fails + +CloudStack controls when a host can/cannot be auto-enabled or auto-disabled by a host detail record (on the host_details table) with key ‘autoenablekvmhost’, in the following way: + +- If a host is auto-enabled or auto-disabled and there is no host detail with key ‘autoenablekvmhost’ for that host, then a new host detail record is created with the key ‘autoenablekvmhost’ and is set to ‘true’ (just before the host is auto-enabled/auto-disabled) +- If the administrator manually disables a host and there is a host detail with key ‘autoenablekvmhost’ for that host, then the host detail ‘autoenablekvmhost’ is set to ‘false’ (indicating that the host cannot be auto-enabled if the health check succeeds) +- If the administrator manually enables a host and there is a host detail with key ‘autoenablekvmhost’ for that host, then the host detail ‘autoenablekvmhost’ is set to ‘true’ (indicating that the host can be auto-disabled if the health check fails) +- If the feature was never enabled before ('enable.kvm.host.auto.enable.disable' global and cluster settings having their default values) and the administrator enables/disables hosts in the cluster, then the host detail with key ‘autoenablekvmhost’ is not created for the hosts. (preserving the usual behavior). If the cluster setting is then enabled, and the administrator enables/disables the host manually then the host detail with key '‘autoenablekvmhost’ is created, and is set to true/false. diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst index d91d69fc11..040ad1cd67 100644 --- a/source/adminguide/index.rst +++ b/source/adminguide/index.rst @@ -69,11 +69,11 @@ Setting up Networking for Users :maxdepth: 4 networking - autoscale_without_netscaler + autoscale_with_virtual_router -Working with Virtual Machines ------------------------------ +Working with Instances +---------------------- .. toctree:: :maxdepth: 4 @@ -89,6 +89,13 @@ Working with Templates & ISOs templates +Working with Clusters +------------------ + +.. toctree:: + :maxdepth: 4 + + clusters Working with Hosts ------------------ @@ -108,8 +115,8 @@ Working with Storage storage -Working with System Virtual Machines ------------------------------------- +Working with System VMs +----------------------- .. toctree:: :maxdepth: 4 @@ -125,6 +132,15 @@ Working with Usage usage +Managing VM and Volume Allocation +--------------------------------- + +.. toctree:: + :maxdepth: 4 + + host_and_storage_tags + arch_types + vm_volume_allocators Managing Networks and Traffic ----------------------------- @@ -134,6 +150,7 @@ Managing Networks and Traffic networking_and_traffic networking/using_remote_access + networking/vnf_templates_appliances Managing the Cloud @@ -171,3 +188,21 @@ Events and Troubleshooting events troubleshooting + + +Extensions +---------- + +.. toctree:: + :maxdepth: 4 + + extensions + + +Best Practices +-------------- + +.. toctree:: + :maxdepth: 4 + + best_practices diff --git a/source/adminguide/locale/pot/hosts.pot b/source/adminguide/locale/pot/hosts.pot index 5ef7fbe455..1678b60fab 100644 --- a/source/adminguide/locale/pot/hosts.pot +++ b/source/adminguide/locale/pot/hosts.pot @@ -262,7 +262,7 @@ msgstr "" #: ../../hosts.rst:171 # 400a182ceace4cef87ffe6c731ea45cd -msgid "Then you may power down the Host, re-use its IP address, re-install it, etc" +msgid "Then you may power down the Host, reuse its IP address, re-install it, etc" msgstr "" #: ../../hosts.rst:176 @@ -545,7 +545,7 @@ msgstr "" #: ../../hosts.rst:410 # 4574765089c64df0a53ffd4b0d9052a0 -msgid "Fill in your desired over-provisioning multipliers in the fields CPU overcommit factor and RAM overcommit factor. The value which is intially shown in these fields is the default value inherited from the global configuration settings." +msgid "Fill in your desired over-provisioning multipliers in the fields CPU overcommit factor and RAM overcommit factor. The value which is initially shown in these fields is the default value inherited from the global configuration settings." msgstr "" #: ../../hosts.rst:421 @@ -772,7 +772,7 @@ msgstr "" #: ../../hosts.rst:530 # 47af367fd0e74e9c98c07d5fd93d9a6a -msgid "The former behaviour also is supported — VLAN is randomly allocated to a network from the VNET range of the physical network when the network turns to Implemented state. The VLAN is released back to the VNET pool when the network shuts down as a part of the Network Garbage Collection. The VLAN can be re-used either by the same network when it is implemented again, or by any other network. On each subsequent implementation of a network, a new VLAN can be assigned." +msgid "The former behaviour also is supported — VLAN is randomly allocated to a network from the VNET range of the physical network when the network turns to Implemented state. The VLAN is released back to the VNET pool when the network shuts down as a part of the Network Garbage Collection. The VLAN can be reused either by the same network when it is implemented again, or by any other network. On each subsequent implementation of a network, a new VLAN can be assigned." msgstr "" #: ../../hosts.rst:538 diff --git a/source/adminguide/locale/pot/management.pot b/source/adminguide/locale/pot/management.pot index cf7bfff0a7..04596b1bc7 100644 --- a/source/adminguide/locale/pot/management.pot +++ b/source/adminguide/locale/pot/management.pot @@ -298,7 +298,7 @@ msgstr "" #: ../../management.rst:345 # 653fb8fc18ea4f17ab01fe630ed6783b -msgid "CloudStack generates a syslog message for every alert. Each syslog message incudes the fields alertType, message, podId, dataCenterId, and clusterId, in the following format. If any field does not have a valid value, it will not be included." +msgid "CloudStack generates a syslog message for every alert. Each syslog message includes the fields alertType, message, podId, dataCenterId, and clusterId, in the following format. If any field does not have a valid value, it will not be included." msgstr "" #: ../../management.rst:354 diff --git a/source/adminguide/locale/pot/networking/external_firewalls_and_load_balancers.pot b/source/adminguide/locale/pot/networking/external_firewalls_and_load_balancers.pot index fa7cea98ca..946305e61e 100644 --- a/source/adminguide/locale/pot/networking/external_firewalls_and_load_balancers.pot +++ b/source/adminguide/locale/pot/networking/external_firewalls_and_load_balancers.pot @@ -503,12 +503,12 @@ msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:456 # 0ac0707e74464bd0840f60e335716a25 -msgid "Ensure that the endpointe.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." +msgid "Ensure that the endpoint.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:464 # f8d93cd584a54fd8b2a72143d4107323 -msgid "If you update the endpointe.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." +msgid "If you update the endpoint.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:468 diff --git a/source/adminguide/locale/pot/networking/inter_vlan_routing.pot b/source/adminguide/locale/pot/networking/inter_vlan_routing.pot index d7b6b8009d..bc8643d755 100644 --- a/source/adminguide/locale/pot/networking/inter_vlan_routing.pot +++ b/source/adminguide/locale/pot/networking/inter_vlan_routing.pot @@ -38,7 +38,7 @@ msgstr "" #: ../../networking/inter_vlan_routing.rst:37 # dca4c4be393c4d7bbcda75f49ffc8efc -msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly alloted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." +msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly allotted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." msgstr "" #: ../../networking/inter_vlan_routing.rst:43 diff --git a/source/adminguide/locale/pot/networking/ip_reservation_in_guest_networks.pot b/source/adminguide/locale/pot/networking/ip_reservation_in_guest_networks.pot index 4d28e100e1..315d15163e 100644 --- a/source/adminguide/locale/pot/networking/ip_reservation_in_guest_networks.pot +++ b/source/adminguide/locale/pot/networking/ip_reservation_in_guest_networks.pot @@ -68,7 +68,7 @@ msgstr "" #: ../../networking/ip_reservation_in_guest_networks.rst:60 # 0710411bb18c4764970dffcc49fe5dab -msgid "You cannot apply IP Reservation if any VM is alloted with an IP address that is outside the Guest VM CIDR." +msgid "You cannot apply IP Reservation if any VM is allotted with an IP address that is outside the Guest VM CIDR." msgstr "" #: ../../networking/ip_reservation_in_guest_networks.rst:63 diff --git a/source/adminguide/locale/pot/networking/persistent_networks.pot b/source/adminguide/locale/pot/networking/persistent_networks.pot index 5db6bc1957..ae8f3c4387 100644 --- a/source/adminguide/locale/pot/networking/persistent_networks.pot +++ b/source/adminguide/locale/pot/networking/persistent_networks.pot @@ -33,7 +33,7 @@ msgstr "" #: ../../networking/persistent_networks.rst:33 # 87f88f46858c41ba96f785b7c3122342 -msgid "One of the advantages of having a persistent network is that you can create a VPC with a tier consisting of only physical devices. For example, you might create a VPC for a three-tier application, deploy VMs for Web and Application tier, and use physical machines for the Database tier. Another use case is that if you are providing services by using physical hardware, you can define the network as persistent and therefore even if all its VMs are destroyed the services will not be discontinued." +msgid "One of the advantages of having a persistent network is that you can create a VPC with a temtier consisting of only physical devices. For example, you might create a VPC for a three-tier application, deploy VMs for Web and Application tier, and use physical machines for the Database tier. Another use case is that if you are providing services by using physical hardware, you can define the network as persistent and therefore even if all its VMs are destroyed the services will not be discontinued." msgstr "" #: ../../networking/persistent_networks.rst:44 diff --git a/source/adminguide/locale/pot/networking/virtual_private_cloud_config.pot b/source/adminguide/locale/pot/networking/virtual_private_cloud_config.pot index 9f29a3ac43..2bb1162f05 100644 --- a/source/adminguide/locale/pot/networking/virtual_private_cloud_config.pot +++ b/source/adminguide/locale/pot/networking/virtual_private_cloud_config.pot @@ -1547,7 +1547,7 @@ msgstr "" #: ../../networking/virtual_private_cloud_config.rst:1165 # 2e6d402ef3d044488597c6501ca6749d # f974a014675745ceae4ebb19113bc49e -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "" #: ../../networking/virtual_private_cloud_config.rst:961 diff --git a/source/adminguide/locale/pot/networking2.pot b/source/adminguide/locale/pot/networking2.pot index 33ea3379ef..8f769f4eea 100644 --- a/source/adminguide/locale/pot/networking2.pot +++ b/source/adminguide/locale/pot/networking2.pot @@ -970,7 +970,7 @@ msgstr "" #: ../../networking2.rst:637 # 7cd262eb2864435f953ba2f8d9b2e0a0 -msgid "You cannot apply IP Reservation if any VM is alloted with an IP address that is outside the Guest VM CIDR." +msgid "You cannot apply IP Reservation if any VM is allotted with an IP address that is outside the Guest VM CIDR." msgstr "" #: ../../networking2.rst:642 @@ -2771,12 +2771,12 @@ msgstr "" #: ../../networking2.rst:2451 # c4bb8c60d3214089b1726fe9bea68db1 -msgid "Ensure that the endpointe.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." +msgid "Ensure that the endpoint.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." msgstr "" #: ../../networking2.rst:2459 # f6027494d923450aa21e243d185af107 -msgid "If you update the endpointe.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." +msgid "If you update the endpoint.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." msgstr "" #: ../../networking2.rst:2465 @@ -5097,7 +5097,7 @@ msgstr "" #: ../../networking2.rst:4764 # 9914db80271c45879b3763424ebbbe4e -msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly alloted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." +msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly allotted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." msgstr "" #: ../../networking2.rst:4770 @@ -6272,7 +6272,7 @@ msgstr "" #: ../../networking2.rst:6482 # bfaeb8a949fb4d25a618540dcc365471 # 6c6e4ac1110442ba9ec325328e96bfb8 -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "" #: ../../networking2.rst:6185 diff --git a/source/adminguide/locale/pot/networking_and_traffic.pot b/source/adminguide/locale/pot/networking_and_traffic.pot index b42cc5d962..619619d8ee 100644 --- a/source/adminguide/locale/pot/networking_and_traffic.pot +++ b/source/adminguide/locale/pot/networking_and_traffic.pot @@ -970,7 +970,7 @@ msgstr "" #: ../../networking/ip_reservation_in_guest_networks.rst:60 # 0e5b7bff020d494b9f4e85c641380036 -msgid "You cannot apply IP Reservation if any VM is alloted with an IP address that is outside the Guest VM CIDR." +msgid "You cannot apply IP Reservation if any VM is allotted with an IP address that is outside the Guest VM CIDR." msgstr "" #: ../../networking/ip_reservation_in_guest_networks.rst:63 @@ -2758,12 +2758,12 @@ msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:456 # d8cef4ea8860477489a80f3a715fbd90 -msgid "Ensure that the endpointe.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." +msgid "Ensure that the endpoint.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server's cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:464 # 1cd70adcb30d47abbcc3dc69e3707036 -msgid "If you update the endpointe.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." +msgid "If you update the endpoint.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`." msgstr "" #: ../../networking/external_firewalls_and_load_balancers.rst:468 @@ -5088,7 +5088,7 @@ msgstr "" #: ../../networking/inter_vlan_routing.rst:37 # 3e6de8dbeba5419abdb2b03019116141 -msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly alloted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." +msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly allotted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." msgstr "" #: ../../networking/inter_vlan_routing.rst:43 @@ -6263,7 +6263,7 @@ msgstr "" #: ../../networking/virtual_private_cloud_config.rst:1165 # d6358f1cb80b45c6becf012d6670f0ff # 19877c93762c4d95b38bfafc90fc110c -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "" #: ../../networking/virtual_private_cloud_config.rst:963 diff --git a/source/adminguide/locale/pot/service_offerings.pot b/source/adminguide/locale/pot/service_offerings.pot index 6edb5a3e18..ed535bc4f2 100644 --- a/source/adminguide/locale/pot/service_offerings.pot +++ b/source/adminguide/locale/pot/service_offerings.pot @@ -416,7 +416,7 @@ msgstr "" #: ../../service_offerings.rst:304 # 665e3b5c270e42979195e2837591595b -msgid "Custom IOPS. If checked, the user can set their own IOPS. If not checked, the root administrator can define values. If the root admin does not set values when using storage QoS, default values are used (the defauls can be overridden if the proper parameters are passed into CloudStack when creating the primary storage in question)." +msgid "Custom IOPS. If checked, the user can set their own IOPS. If not checked, the root administrator can define values. If the root admin does not set values when using storage QoS, default values are used (the defaults can be overridden if the proper parameters are passed into CloudStack when creating the primary storage in question)." msgstr "" #: ../../service_offerings.rst:311 diff --git a/source/adminguide/locale/pot/storage.pot b/source/adminguide/locale/pot/storage.pot index e6cdb16aec..8a9161d444 100644 --- a/source/adminguide/locale/pot/storage.pot +++ b/source/adminguide/locale/pot/storage.pot @@ -1011,7 +1011,7 @@ msgstr "" #: ../../storage.rst:685 # bc81c587ad8b4032b27d61690390e258 -msgid "With each snapshot schedule, users can also specify the number of scheduled snapshots to be retained. Older snapshots that exceed the retention limit are automatically deleted. This user-defined limit must be equal to or lower than the global limit set by the CloudStack administrator. See `“Globally Configured Limits” `_. The limit applies only to those snapshots that are taken as part of an automatic recurring snapshot policy. Additional manual snapshots can be created and retained." +msgid "With each reccurring snapshot schedule, users can also specify the number of recurring snapshots to be retained. Older snapshots that exceed the retention limit are automatically deleted. This user-defined limit must be equal to or lower than the global limit set by the CloudStack administrator. See `“Globally Configured Limits” `_. The limit applies only to those snapshots that are taken as part of an automatic recurring snapshot policy. Additional manual snapshots can be created and retained." msgstr "" #: ../../storage.rst:697 diff --git a/source/adminguide/locale/pot/systemvm.pot b/source/adminguide/locale/pot/systemvm.pot index 63cea3fd24..956c2fdabc 100644 --- a/source/adminguide/locale/pot/systemvm.pot +++ b/source/adminguide/locale/pot/systemvm.pot @@ -103,7 +103,7 @@ msgstr "" #: ../../systemvm.rst:66 # 6ea0f846b0a34711b7c0090cb48d8c32 -msgid "http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-xen.vhd.bz2" +msgid "http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-xen.vhd.bz2" msgstr "" #: ../../systemvm.rst:67 @@ -113,7 +113,7 @@ msgstr "" #: ../../systemvm.rst:67 # fe251bca2b854129890cba8e7ac9bbbf -msgid "http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-kvm.qcow2.bz2" +msgid "http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-kvm.qcow2.bz2" msgstr "" #: ../../systemvm.rst:70 diff --git a/source/adminguide/locale/pot/templates.pot b/source/adminguide/locale/pot/templates.pot index be9832fd02..e29f6e7beb 100644 --- a/source/adminguide/locale/pot/templates.pot +++ b/source/adminguide/locale/pot/templates.pot @@ -1160,7 +1160,7 @@ msgstr "" #: ../../templates.rst:1039 # 7dfc38f9a99c4d0bbb5007329350693e -msgid "`http://download.cloud.com/templates/4.2/bindir/cloud-set-guest-password.in `_" +msgid "`http://download.cloudstack.org/templates/4.2/bindir/cloud-set-guest-password.in `_" msgstr "" #: ../../templates.rst:1042 diff --git a/source/adminguide/locale/pot/troubleshooting.pot b/source/adminguide/locale/pot/troubleshooting.pot index 979a74e127..33da45dc8c 100644 --- a/source/adminguide/locale/pot/troubleshooting.pot +++ b/source/adminguide/locale/pot/troubleshooting.pot @@ -283,7 +283,7 @@ msgstr "" #: ../../troubleshooting.rst:244 # 5f383b9190f34ebcbdd6bb92b713ee21 -msgid "Below are a few troubleshooting steps to check whats going wrong with your network..." +msgid "Below are a few troubleshooting steps to check what's going wrong with your network..." msgstr "" #: ../../troubleshooting.rst:249 @@ -308,7 +308,7 @@ msgstr "" #: ../../troubleshooting.rst:271 # 417a511656394e62ab6533726322a54e -msgid "If the pings dont work, run *tcpdump(8)* all over the place to check who is gobbling up the packets. Ultimately, if the switches are not configured correctly, CloudStack networking wont work so fix the physical networking issues before you proceed to the next steps" +msgid "If the pings dont work, run *tcpdump(8)* all over the place to check who is gobbling up the packets. Ultimately, if the switches are not configured correctly, CloudStack networking won't work so fix the physical networking issues before you proceed to the next steps" msgstr "" #: ../../troubleshooting.rst:276 @@ -333,7 +333,7 @@ msgstr "" #: ../../troubleshooting.rst:321 # d7be5d89abc2416a81c2e11ae80e5c5e -msgid "KVM traffic labels require to be named as *\"cloudbr0\"*, *\"cloudbr2\"*, *\"cloudbrN\"* etc and the corresponding bridge must exist on the KVM hosts. If you create labels/bridges with any other names, CloudStack (atleast earlier versions did) seems to ignore them. CloudStack does not create the physical bridges on the KVM hosts, you need to create them **before** before adding the host to Cloudstack." +msgid "KVM traffic labels require to be named as *\"cloudbr0\"*, *\"cloudbr2\"*, *\"cloudbrN\"* etc and the corresponding bridge must exist on the KVM hosts. If you create labels/bridges with any other names, CloudStack (at least earlier versions did) seems to ignore them. CloudStack does not create the physical bridges on the KVM hosts, you need to create them **before** before adding the host to Cloudstack." msgstr "" #: ../../troubleshooting.rst:340 @@ -348,7 +348,7 @@ msgstr "" #: ../../troubleshooting.rst:385 # e75bf706d6a745c9a94ee34516e86d1f -msgid "The Internet would be accessible from both the SSVM and CPVM instances by default. Their public IPs will also be directly pingable from the Internet. Please note that these test would work only if your switches and traffic labels are configured correctly for your environment. If your SSVM/CPVM cant reach the Internet, its very unlikely that the Virtual Router (VR) can also the reach the Internet suggesting that its either a switching issue or incorrectly assigned traffic labels. Fix the SSVM/CPVM issues before you debug VR issues." +msgid "The Internet would be accessible from both the SSVM and CPVM instances by default. Their public IPs will also be directly pingable from the Internet. Please note that these test would work only if your switches and traffic labels are configured correctly for your environment. If your SSVM/CPVM can't reach the Internet, its very unlikely that the Virtual Router (VR) can also the reach the Internet suggesting that its either a switching issue or incorrectly assigned traffic labels. Fix the SSVM/CPVM issues before you debug VR issues." msgstr "" #: ../../troubleshooting.rst:417 @@ -358,12 +358,12 @@ msgstr "" #: ../../troubleshooting.rst:432 # fd961e75e43d4c48a4b779ef136e1d12 -msgid "However, the Virtual Router's (VR) Source NAT Public IP address **WONT** be reachable until appropriate Ingress rules are in place. You can add *Ingress* rules under *Network, Guest Network, IP Address, Firewall* setting page." +msgid "However, the Virtual Router's (VR) Source NAT Public IP address **WON'T** be reachable until appropriate Ingress rules are in place. You can add *Ingress* rules under *Network, Guest Network, IP Address, Firewall* setting page." msgstr "" #: ../../troubleshooting.rst:439 # 7a1ba3d03cd64a0cb60486d361453ebd -msgid "The VM Instances by default wont be able to access the Internet. Add Egress rules to permit traffic." +msgid "The VM Instances by default won't be able to access the Internet. Add Egress rules to permit traffic." msgstr "" #: ../../troubleshooting.rst:444 @@ -378,6 +378,6 @@ msgstr "" #: ../../troubleshooting.rst:454 # 5fff1dc7083a4412a9e4051f2e239180 -msgid "This section was contibuted by Shanker Balan and was originally published on `Shapeblue's blog `_" +msgid "This section was contributed by Shanker Balan and was originally published on `Shapeblue's blog `_" msgstr "" diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/hosts.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/hosts.po index 7b0786ac75..8b8abb5127 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/hosts.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/hosts.po @@ -317,7 +317,7 @@ msgstr "使用UI选项来移除主机。" # 400a182ceace4cef87ffe6c731ea45cd #: ../../hosts.rst:171 msgid "" -"Then you may power down the Host, re-use its IP address, re-install it, etc" +"Then you may power down the Host, reuse its IP address, re-install it, etc" msgstr "然后你可以关掉主机，重用它的IP地址，重新安装系统，等等。" # b9297a05564a41f8aa6995f8f1e2265a @@ -702,7 +702,7 @@ msgstr "选择你要操作的群集，点击编辑按钮。" #: ../../hosts.rst:410 msgid "" "Fill in your desired over-provisioning multipliers in the fields CPU " -"overcommit factor and RAM overcommit factor. The value which is intially shown" +"overcommit factor and RAM overcommit factor. The value which is initially shown" " in these fields is the default value inherited from the global " "configuration settings." msgstr "在CPU overcommit ratio和RAM overcommit ratio区域里填入你希望的超配系数。这里的初始值是从全局配置设置里继承而来的。" @@ -988,7 +988,7 @@ msgid "" "network from the VNET range of the physical network when the network turns " "to Implemented state. The VLAN is released back to the VNET pool when the " "network shuts down as a part of the Network Garbage Collection. The VLAN can" -" be re-used either by the same network when it is implemented again, or by " +" be reused either by the same network when it is implemented again, or by " "any other network. On each subsequent implementation of a network, a new " "VLAN can be assigned." msgstr "同样被支持—当网络转换为运行状态是，VLAN是随机地通过物理网络的VNET范围分配给网络。当网络作为网络垃圾回收过程的一部分而关闭时，VLAN会被回收到VNET池。当网络再次启用的时候VLAN还能被其重用，或者其他网络使用。在每个新启用的网络中，都有一个新的VLAN被分配。" diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/management.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/management.po index 585e04be42..6d55fdbe2f 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/management.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/management.po @@ -363,7 +363,7 @@ msgstr "Syslog警报详情" #: ../../management.rst:345 msgid "" "CloudStack generates a syslog message for every alert. Each syslog message " -"incudes the fields alertType, message, podId, dataCenterId, and clusterId, " +"includes the fields alertType, message, podId, dataCenterId, and clusterId, " "in the following format. If any field does not have a valid value, it will " "not be included." msgstr "CloudStack为每个警告生成一个syslog信息。每个syslog信息包含下列格式的字段alertType、message、podId、dataCenterId和clusterId。如果任何字段没有有效值的话，它将不会包含在内。" diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/external_firewalls_and_load_balancers.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/external_firewalls_and_load_balancers.po index f1e674dbb1..0eacca4b84 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/external_firewalls_and_load_balancers.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/external_firewalls_and_load_balancers.po @@ -729,7 +729,7 @@ msgstr "" # 0ac0707e74464bd0840f60e335716a25 #: ../../networking/external_firewalls_and_load_balancers.rst:456 msgid "" -"Ensure that the endpointe.url parameter present in the Global Settings is " +"Ensure that the endpoint.url parameter present in the Global Settings is " "set to the Management Server API URL. For example, " "``http://10.102.102.22:8080/client/api``. In a multi-node Management Server " "deployment, use the virtual IP address configured in the load balancer for " @@ -740,10 +740,10 @@ msgstr "确保在全局配置中的结束点地址参数已设置为管理服务 # f8d93cd584a54fd8b2a72143d4107323 #: ../../networking/external_firewalls_and_load_balancers.rst:464 msgid "" -"If you update the endpointe.url, disable the AutoScale functionality of the " +"If you update the endpoint.url, disable the AutoScale functionality of the " "load balancer rules in the system, then enable them back to reflect the " "changes. For more information see :ref:`update-autoscale`." -msgstr "如果更新了endpointe.url，在系统自动负载均衡器规则里，先关闭自缩放功能随后再开启，以应用此更新。。更多信息，参见 :ref:`update-autoscale`。" +msgstr "如果更新了endpoint.url，在系统自动负载均衡器规则里，先关闭自缩放功能随后再开启，以应用此更新。。更多信息，参见 :ref:`update-autoscale`。" # f4e671d2a1814ee7936944319291f882 #: ../../networking/external_firewalls_and_load_balancers.rst:468 diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/inter_vlan_routing.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/inter_vlan_routing.po index c2517b7938..b784662c5f 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/inter_vlan_routing.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/inter_vlan_routing.po @@ -53,7 +53,7 @@ msgstr "主要的优势为：" #: ../../networking/inter_vlan_routing.rst:37 msgid "" "The administrator can deploy a set of VLANs and allow users to deploy VMs on" -" these VLANs. A guest VLAN is randomly alloted to an account from a pre-" +" these VLANs. A guest VLAN is randomly allotted to an account from a pre-" "specified set of guest VLANs. All the VMs of a certain tier of an account " "reside on the guest VLAN allotted to that account." msgstr "管理可以部署一个vlans集，同时运行用户部署虚拟机在这些vlan上。从预先指定的vlan集中随机的为租户分配一个来宾vlan.租户处于同一层的所有vm处于分配给这个租户的来宾vlan." diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/ip_reservation_in_guest_networks.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/ip_reservation_in_guest_networks.po index 2b2be7d4e8..d7e1080722 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/ip_reservation_in_guest_networks.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/ip_reservation_in_guest_networks.po @@ -93,7 +93,7 @@ msgstr "指定一个有效的客户虚拟机CIDR。只有不活动的IP在客户 # 0710411bb18c4764970dffcc49fe5dab #: ../../networking/ip_reservation_in_guest_networks.rst:60 msgid "" -"You cannot apply IP Reservation if any VM is alloted with an IP address that" +"You cannot apply IP Reservation if any VM is allotted with an IP address that" " is outside the Guest VM CIDR." msgstr "如果任一虚拟机被分配了客户虚拟机CIDR之外的IP地址时，IP预留将不能应用。" diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/virtual_private_cloud_config.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/virtual_private_cloud_config.po index c0efde4c74..553c3bf8c4 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/virtual_private_cloud_config.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking/virtual_private_cloud_config.po @@ -1820,7 +1820,7 @@ msgstr "使用用户或管理员登录到CloudStack用户界面。" # f974a014675745ceae4ebb19113bc49e #: ../../networking/virtual_private_cloud_config.rst:959 #: ../../networking/virtual_private_cloud_config.rst:1165 -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "下拉选择方案，选择网络方案：" # 08107e25d3ae4ed5a4e72a9ef68249af diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking2.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking2.po index 2ec73d92ee..d5fb26845f 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking2.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking2.po @@ -1046,7 +1046,7 @@ msgstr "指定一个有效的客户虚拟机CIDR。只有不活动的IP在客户 # 7cd262eb2864435f953ba2f8d9b2e0a0 #: ../../networking2.rst:637 msgid "" -"You cannot apply IP Reservation if any VM is alloted with an IP address that" +"You cannot apply IP Reservation if any VM is allotted with an IP address that" " is outside the Guest VM CIDR." msgstr "如果任一虚拟机被分配了客户虚拟机CIDR之外的IP地址时，IP预留将不能应用。" @@ -6338,7 +6338,7 @@ msgstr "主要的优势为：" #: ../../networking2.rst:4764 msgid "" "The administrator can deploy a set of VLANs and allow users to deploy VMs on" -" these VLANs. A guest VLAN is randomly alloted to an account from a pre-" +" these VLANs. A guest VLAN is randomly allotted to an account from a pre-" "specified set of guest VLANs. All the VMs of a certain tier of an account " "reside on the guest VLAN allotted to that account." msgstr "管理可以部署一个vlans集，同时运行用户部署虚拟机在这些vlan上。从预先指定的vlan集中随机的为租户分配一个来宾vlan.租户处于同一层的所有vm处于分配给这个租户的来宾vlan." @@ -7792,7 +7792,7 @@ msgstr "使用用户或管理员登录到CloudStack用户界面。" # bfaeb8a949fb4d25a618540dcc365471 # 6c6e4ac1110442ba9ec325328e96bfb8 #: ../../networking2.rst:6177 ../../networking2.rst:6482 -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "下拉选择方案，选择网络方案：" # 7d4dc49f6e224caa9bee24da2b622a4c diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking_and_traffic.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking_and_traffic.po index ec94b4aa4e..ae047772c5 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/networking_and_traffic.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/networking_and_traffic.po @@ -1127,7 +1127,7 @@ msgstr "指定一个有效的客户虚拟机CIDR。只有不活动的IP在客户 # 0e5b7bff020d494b9f4e85c641380036 #: ../../networking/ip_reservation_in_guest_networks.rst:60 msgid "" -"You cannot apply IP Reservation if any VM is alloted with an IP address that" +"You cannot apply IP Reservation if any VM is allotted with an IP address that" " is outside the Guest VM CIDR." msgstr "如果任一虚拟机被分配了客户虚拟机CIDR之外的IP地址时，IP预留将不能应用。" @@ -6544,7 +6544,7 @@ msgstr "主要的优势为：" #: ../../networking/inter_vlan_routing.rst:37 msgid "" "The administrator can deploy a set of VLANs and allow users to deploy VMs on" -" these VLANs. A guest VLAN is randomly alloted to an account from a pre-" +" these VLANs. A guest VLAN is randomly allotted to an account from a pre-" "specified set of guest VLANs. All the VMs of a certain tier of an account " "reside on the guest VLAN allotted to that account." msgstr "管理可以部署一个vlans集，同时运行用户部署虚拟机在这些vlan上。从预先指定的vlan集中随机的为租户分配一个来宾vlan.租户处于同一层的所有vm处于分配给这个租户的来宾vlan." @@ -8012,7 +8012,7 @@ msgstr "使用用户或管理员登录到CloudStack用户界面。" # 19877c93762c4d95b38bfafc90fc110c #: ../../networking/virtual_private_cloud_config.rst:959 #: ../../networking/virtual_private_cloud_config.rst:1165 -msgid "Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses." +msgid "Navigate to Service Offerings and choose Network OfferingPublic IP Addresses." msgstr "下拉选择方案，选择网络方案：" # 34b1dc57da234cfcbef32cbb10126c3c diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/service_offerings.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/service_offerings.po index b4f468837e..70fa95b6fb 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/service_offerings.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/service_offerings.po @@ -567,7 +567,7 @@ msgstr "QoS　类型。三种可选：空 （ 无服务质量）， hypervisor msgid "" "Custom IOPS. If checked, the user can set their own IOPS. If not checked, " "the root administrator can define values. If the root admin does not set " -"values when using storage QoS, default values are used (the defauls can be " +"values when using storage QoS, default values are used (the defaults can be " "overridden if the proper parameters are passed into CloudStack when creating" " the primary storage in question)." msgstr "订制 IOPS 。 如选中，用户可以设置自己的 IOPS。如未被选中，root 管理员则能够定义该值。如果使用存储 QoS时，root 管理员没有设置该值，则采用默认值（如果创建主存储时考虑到对应的参数被传递到 CloudStack 中，则默认值将被覆盖）" diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/systemvm.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/systemvm.po index c880c7e0d9..eb13e92bb2 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/systemvm.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/systemvm.po @@ -125,9 +125,9 @@ msgstr "XenServer" # 6ea0f846b0a34711b7c0090cb48d8c32 #: ../../systemvm.rst:66 msgid "" -"http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15" +"http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15" "-master-xen.vhd.bz2" -msgstr "http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-xen.vhd.bz2" +msgstr "http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-xen.vhd.bz2" # e8a51da6f6614114a91e4006eedfc912 #: ../../systemvm.rst:67 @@ -137,9 +137,9 @@ msgstr "KVM" # fe251bca2b854129890cba8e7ac9bbbf #: ../../systemvm.rst:67 msgid "" -"http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15" +"http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15" "-master-kvm.qcow2.bz2" -msgstr "http://download.cloud.com/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-kvm.qcow2.bz2" +msgstr "http://download.cloudstack.org/templates/4.2/64bit/systemvmtemplate64-2013-07-15-master-kvm.qcow2.bz2" # 2d498240d20c4683ab11ac2232135a16 #: ../../systemvm.rst:70 diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/templates.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/templates.po index 75af44dab5..d6f2ef47e2 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/templates.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/templates.po @@ -1487,10 +1487,10 @@ msgstr "下载cloud-set-guest-password脚本文件：" # 7dfc38f9a99c4d0bbb5007329350693e #: ../../templates.rst:1039 msgid "" -"`http://download.cloud.com/templates/4.2/bindir/cloud-set-guest-password.in " -"`_" -msgstr "`http://download.cloud.com/templates/4.2/bindir/cloud-set-guest-password.in `_" +msgstr "`http://download.cloudstack.org/templates/4.2/bindir/cloud-set-guest-password.in `_" # 6eead5e6602446c78f65d37e092b049f #: ../../templates.rst:1042 diff --git a/source/adminguide/locale/zh_CN/LC_MESSAGES/troubleshooting.po b/source/adminguide/locale/zh_CN/LC_MESSAGES/troubleshooting.po index b042c29a71..4a8e5409f2 100644 --- a/source/adminguide/locale/zh_CN/LC_MESSAGES/troubleshooting.po +++ b/source/adminguide/locale/zh_CN/LC_MESSAGES/troubleshooting.po @@ -338,7 +338,7 @@ msgstr "故障排查网络传输" # 5f383b9190f34ebcbdd6bb92b713ee21 #: ../../troubleshooting.rst:244 msgid "" -"Below are a few troubleshooting steps to check whats going wrong with your " +"Below are a few troubleshooting steps to check what's going wrong with your " "network..." msgstr "在下列故障排查步骤中检验你网络中出现的故障..." @@ -370,7 +370,7 @@ msgstr "在*host2 (kvm2)*上" msgid "" "If the pings dont work, run *tcpdump(8)* all over the place to check who is " "gobbling up the packets. Ultimately, if the switches are not configured " -"correctly, CloudStack networking wont work so fix the physical networking " +"correctly, CloudStack networking won't work so fix the physical networking " "issues before you proceed to the next steps" msgstr "如果ping不通，运行 *tcpdump(8)*在所有VLAN上检查丢失的数据包。最终，如果交换机配置失败，CloudStack网络将无法工作，所以在处理下一部前要确定物理网络设备的问题。" @@ -407,7 +407,7 @@ msgstr "列出正在使用的*CloudMonkey*" msgid "" "KVM traffic labels require to be named as *\"cloudbr0\"*, *\"cloudbr2\"*, " "*\"cloudbrN\"* etc and the corresponding bridge must exist on the KVM hosts." -" If you create labels/bridges with any other names, CloudStack (atleast " +" If you create labels/bridges with any other names, CloudStack (at least " "earlier versions did) seems to ignore them. CloudStack does not create the " "physical bridges on the KVM hosts, you need to create them **before** before" " adding the host to Cloudstack." @@ -440,7 +440,7 @@ msgid "" "The Internet would be accessible from both the SSVM and CPVM instances by " "default. Their public IPs will also be directly pingable from the Internet. " "Please note that these test would work only if your switches and traffic " -"labels are configured correctly for your environment. If your SSVM/CPVM cant" +"labels are configured correctly for your environment. If your SSVM/CPVM can't" " reach the Internet, its very unlikely that the Virtual Router (VR) can also" " the reach the Internet suggesting that its either a switching issue or " "incorrectly assigned traffic labels. Fix the SSVM/CPVM issues before you " @@ -458,16 +458,16 @@ msgstr "除非有些Egress规则，Virtual Router(VR)也是不能到达Internet # fd961e75e43d4c48a4b779ef136e1d12 #: ../../troubleshooting.rst:432 msgid "" -"However, the Virtual Router's (VR) Source NAT Public IP address **WONT** be " +"However, the Virtual Router's (VR) Source NAT Public IP address **WON'T** be " "reachable until appropriate Ingress rules are in place. You can add " "*Ingress* rules under *Network, Guest Network, IP Address, Firewall* setting" " page." -msgstr "尽管如此，Virtual Router(VR) Source NAT Pulic IP地址除非有近似的Ingress规则在此，要么**WONT** 达到。你可以添加 *Ingress* rules under *Network, Guest Network, IP Address, Firewall* 设置页。" +msgstr "尽管如此，Virtual Router(VR) Source NAT Pulic IP地址除非有近似的Ingress规则在此，要么**WON'T** 达到。你可以添加 *Ingress* rules under *Network, Guest Network, IP Address, Firewall* 设置页。" # 7a1ba3d03cd64a0cb60486d361453ebd #: ../../troubleshooting.rst:439 msgid "" -"The VM Instances by default wont be able to access the Internet. Add Egress " +"The VM Instances by default won't be able to access the Internet. Add Egress " "rules to permit traffic." msgstr "默认的VM Instances不能够连接Internet。添加Egress规则后可允许连接。" @@ -491,7 +491,7 @@ msgstr "在海量的实例中，问题会出现在交换层，原因是L3的配 # 5fff1dc7083a4412a9e4051f2e239180 #: ../../troubleshooting.rst:454 msgid "" -"This section was contibuted by Shanker Balan and was originally published on" +"This section was contributed by Shanker Balan and was originally published on" " `Shapeblue's blog `_" msgstr "这些内容有Shanker Balan贡献，其原文发布在`Shapeblue'博客中`_" diff --git a/source/adminguide/management.rst b/source/adminguide/management.rst index 0861ff153e..bdaedac062 100644 --- a/source/adminguide/management.rst +++ b/source/adminguide/management.rst @@ -14,19 +14,21 @@ under the License. +.. _resource-tags: + Using Tags to Organize Resources in the Cloud --------------------------------------------- A tag is a key-value pair that stores metadata about a resource in the cloud. Tags are useful for categorizing resources. For example, you can -tag a user VM with a value that indicates the user's city of residence. +tag a User Instance with a value that indicates the User's city of residence. In this case, the key would be "city" and the value might be "Toronto" or "Tokyo." You can then request CloudStack to find all resources that -have a given tag; for example, VMs for users in a given city. +have a given tag; for example, Instances for Users in a given city. -You can tag a user virtual machine, volume, snapshot, guest network, -template, ISO, firewall rule, port forwarding rule, public IP address, -security group, load balancer rule, project, VPC, network ACL, or static +You can tag a User Instance, Volume, Snapshot, Guest Network, +Template, ISO, firewall rule, port forwarding rule, public IP address, +security group, load balancer rule, project, VPC, Network ACL, or static route. You can not tag a remote access VPN. You can work with tags through the UI or through the API commands @@ -84,7 +86,7 @@ The following API commands have the "tags" input parameter: Using Comments on the Resources in the Cloud -------------------------------------------- -CloudStack allows users and administrators to create comments against cloud objects with a UUID. The listing page of any cloud object includes a blue icon next to the object name indicating that the object contains comments. +CloudStack allows Users and administrators to create comments against cloud objects with a UUID. The listing page of any cloud object includes a blue icon next to the object name indicating that the object contains comments. To create a new comment on an object: @@ -97,13 +99,13 @@ To create a new comment on an object: .. note:: Administrators only: Select the 'Only visible to Administrators' checkbox to create private comments across administrators -To display al the comments created by the logged in user (or administrator): +To display al the comments created by the logged in User (or administrator): 1. In the left navigation bar, click Tools 2. Click Comments (the default filter is 'Created by me') -To display all the comments on the objects that the logged in user (or administrator) has access: +To display all the comments on the objects that the logged in User (or administrator) has access: 1. In the left navigation bar, click Tools @@ -179,7 +181,7 @@ add the encrypted password to .. code:: bash - # java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.2.jar \ org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh \ input="newpassword123" password="`cat /etc/cloudstack/management/key`" \ verbose=false + # java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar com.cloud.utils.crypt.EncryptionCLI -p `cat /etc/cloudstack/management/key` -i newpassword123 File encryption type @@ -215,8 +217,8 @@ cloud. Alerts are notices to an administrator, generally delivered by e-mail, notifying the administrator that an error has occurred in the cloud. Alert behavior is configurable. -Events track all of the user and administrator actions in the cloud. For -example, every guest VM start creates an associated event. Events are +Events track all of the User and administrator actions in the cloud. For +example, every Guest Instance start creates an associated event. Events are stored in the Management Server’s database. Emails will be sent to administrators under the following circumstances: @@ -229,6 +231,48 @@ Emails will be sent to administrators under the following circumstances: - The Host cluster runs low on CPU, memory, or storage resources +The following global settings are available to configure Alerts via SMTP. + +.. list-table:: Management Alerts Global Settings + :header-rows: 1 + + * - Global setting + - Default + - Description + * - ``alert.smtp.host`` + - `null` + - SMTP hostname used for sending out email alerts. + * - ``alert.smtp.port`` + - `465` + - Port the SMTP server is listening on. + * - ``alert.smtp.useAuth`` + - `false` + - If true, use SMTP authentication when sending emails. + * - ``alert.smtp.username`` + - `null` + - Username for SMTP authentication (applies only if alert.smtp.useAuth is true). + * - ``alert.smtp.password`` + - `null` + - Password for SMTP authentication (applies only if alert.smtp.useAuth is true). + * - ``alert.smtp.useStartTLS`` + - `false` + - If set to true and if we enable security via alert.smtp.useAuth, this will enable StartTLS to secure the connection. + * - ``(alert.smtp.enabledSecurityProtocols`` + - `null` + - White-space separated security protocols; ex: "TLSv1 TLSv1.1". Supported protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1 and TLSv1.2 + * - ``alert.smtp.connectiontimeout`` + - `30000` + - Socket connection timeout value in milliseconds. -1 for infinite timeout. + * - ``alert.smtp.timeout`` + - `30000` + - Socket I/O timeout value in milliseconds. -1 for infinite timeout. + * - ``alert.email.addresses`` + - `null` + - Comma separated list of email addresses which are going to receive alert emails. + * - ``alert.email.sender`` + - `null` + - Sender of alert email (will be in the From header of the email). + Sending Alerts to External SNMP and Syslog Managers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -244,116 +288,96 @@ The alerts which can be sent are: The following is the list of alert type numbers. The current alerts can be found by calling listAlerts. -:: - - MEMORY = 0 // Available Memory below configured threshold - -:: - - CPU = 1 // Unallocated CPU below configured threshold - -:: - - STORAGE =2 // Available Storage below configured threshold - -:: - - STORAGE_ALLOCATED = 3 // Remaining unallocated Storage is below configured threshold - -:: - - PUBLIC_IP = 4 // Number of unallocated virtual network public IPs is below configured threshold - -:: - - PRIVATE_IP = 5 // Number of unallocated private IPs is below configured threshold - -:: - - SECONDARY_STORAGE = 6 // Available Secondary Storage in availability zone is below configured threshold - -:: - - HOST = 7 // Host related alerts like host disconnected - -:: - - USERVM = 8 // User VM stopped unexpectedly - -:: - - DOMAIN_ROUTER = 9 // Domain Router VM stopped unexpectedly - -:: - - CONSOLE_PROXY = 10 // Console Proxy VM stopped unexpectedly - -:: - - ROUTING = 11 // Lost connection to default route (to the gateway) - -:: - - STORAGE_MISC = 12 // Storage issue in system VMs - -:: - - USAGE_SERVER = 13 // No usage server process running - -:: - - MANAGMENT_NODE = 14 // Management network CIDR is not configured originally - -:: - - DOMAIN_ROUTER_MIGRATE = 15 // Domain Router VM Migration was unsuccessful - -:: - - CONSOLE_PROXY_MIGRATE = 16 // Console Proxy VM Migration was unsuccessful - -:: - - USERVM_MIGRATE = 17 // User VM Migration was unsuccessful - -:: - - VLAN = 18 // Number of unallocated VLANs is below configured threshold in availability zone - -:: - - SSVM = 19 // SSVM stopped unexpectedly - -:: - - USAGE_SERVER_RESULT = 20 // Usage job failed - -:: - - STORAGE_DELETE = 21 // Failed to delete storage pool - -:: - - UPDATE_RESOURCE_COUNT = 22 // Failed to update the resource count - -:: - - USAGE_SANITY_RESULT = 23 // Usage Sanity Check failed - -:: - - DIRECT_ATTACHED_PUBLIC_IP = 24 // Number of unallocated shared network IPs is low in availability zone - -:: - - LOCAL_STORAGE = 25 // Remaining unallocated Local Storage is below configured threshold - -:: - - RESOURCE_LIMIT_EXCEEDED = 26 //Generated when the resource limit exceeds the limit. Currently used for recurring snapshots only - - -You can also display the most up to date list by calling the API command ``listAlerts``. +.. list-table:: List of Alerts + :header-rows: 1 + + * - Type Number + - Name + - Description + * - `0` + - ``MEMORY`` + - Available Memory below configured threshold + * - `1` + - ``CPU`` + - Unallocated CPU below configured threshold + * - `2` + - ``STORAGE`` + - Available Storage below configured threshold + * - `3` + - ``STORAGE_ALLOCATED`` + - Remaining unallocated Storage is below configured threshold + * - `4` + - ``PUBLIC_IP`` + - Number of unallocated virtual Network public IPs is below configured threshold + * - `5` + - ``PRIVATE_IP`` + - Number of unallocated private IPs is below configured threshold + * - `6` + - ``SECONDARY_STORAGE`` + - Available Secondary Storage in availability zone is below configured threshold + * - `7` + - ``HOST`` + - Host related alerts like host disconnected + * - `8` + - ``USERVM`` + - User Instance stopped unexpectedly + * - `9` + - ``DOMAIN_ROUTER`` + - Domain Router VM stopped unexpectedly + * - `10` + - ``CONSOLE_PROXY`` + - Console Proxy VM stopped unexpectedly + * - `11` + - ``ROUTING`` + - Lost connection to default route (to the gateway) + * - `12` + - ``STORAGE_MISC`` + - Storage issue in system VMs + * - `13` + - ``USAGE_SERVER`` + - No usage server process running + * - `14` + - ``MANAGEMENT_NODE`` + - Management Network CIDR is not configured originally + * - `15` + - ``DOMAIN_ROUTER_MIGRATE`` + - Domain Router VM Migration was unsuccessful + * - `16` + - ``CONSOLE_PROXY_MIGRATE`` + - Console Proxy VM Migration was unsuccessful + * - `17` + - ``USERVM_MIGRATE`` + - User Instance Migration was unsuccessful + * - `18` + - ``VLAN`` + - Number of unallocated VLANs is below configured threshold in availability zone + * - `19` + - ``SSVM`` + - SSVM stopped unexpectedly + * - `20` + - ``USAGE_SERVER_RESULT`` + - Usage job failed + * - `21` + - ``STORAGE_DELETE`` + - Failed to delete storage pool + * - `22` + - ``UPDATE_RESOURCE_COUNT`` + - Failed to update the resource count + * - `23` + - ``USAGE_SANITY_RESULT`` + - Usage Sanity Check failed + * - `24` + - ``DIRECT_ATTACHED_PUBLIC_IP`` + - Number of unallocated shared Network IPs is low in availability zone + * - `25` + - ``LOCAL_STORAGE`` + - Remaining unallocated Local Storage is below configured threshold + * - `26` + - ``RESOURCE_LIMIT_EXCEEDED`` + - Generated when the resource limit exceeds the limit. Currently used for recurring Snapshots only + + +You can also display the most up to date list by calling the API command ``listAlerts`` or unsing CLoudMonkey ``cmk list alerts``. SNMP Alert Details @@ -369,7 +393,7 @@ Syslog Alert Details ^^^^^^^^^^^^^^^^^^^^ CloudStack generates a syslog message for every alert. Each syslog -message incudes the fields alertType, message, podId, dataCenterId, and +message includes the fields alertType, message, podId, dataCenterId, and clusterId, in the following format. If any field does not have a valid value, it will not be included. @@ -445,7 +469,7 @@ alerts from CloudStack: #. If your cloud has multiple Management Server nodes, repeat these - steps to edit log4j-cloud.xml on every instance. + steps to edit log4j-cloud.xml on every Instance. #. If you have made these changes while the Management Server is running, wait a few minutes for the change to take effect. @@ -469,20 +493,20 @@ Customizing the Network Domain Name ----------------------------------- The root administrator can optionally assign a custom DNS suffix at the -level of a network, account, domain, zone, or entire CloudStack +level of a Network, Account, domain, zone, or entire CloudStack installation, and a domain administrator can do so within their own domain. To specify a custom domain name and put it into effect, follow these steps. #. Set the DNS suffix at the desired scope - - At the network level, the DNS suffix can be assigned through the - UI when creating a new network, as described in + - At the Network level, the DNS suffix can be assigned through the + UI when creating a new Network, as described in `“Adding an Additional Guest Network” `_ or with the updateNetwork command in the CloudStack API. - - At the account, domain, or zone level, the DNS suffix can be + - At the Account, domain, or zone level, the DNS suffix can be assigned with the appropriate CloudStack API commands: createAccount, editAccount, createDomain, editDomain, createZone, or editZone. @@ -492,29 +516,75 @@ these steps. updateConfiguration. After modifying this global configuration, restart the Management Server to put the new setting into effect. -#. To make the new DNS suffix take effect for an existing network, call +#. To make the new DNS suffix take effect for an existing Network, call the CloudStack API command updateNetwork. This step is not necessary - when the DNS suffix was specified while creating a new network. + when the DNS suffix was specified while creating a new Network. -The source of the network domain that is used depends on the following +The source of the Network domain that is used depends on the following rules. -- For all networks, if a network domain is specified as part of a - network's own configuration, that value is used. +- For all Networks, if a Network domain is specified as part of a + Network's own configuration, that value is used. -- For an account-specific network, the network domain specified for the - account is used. If none is specified, the system looks for a value +- For an Account-specific Network, the Network domain specified for the + Account is used. If none is specified, the system looks for a value in the domain, zone, and global configuration, in that order. -- For a domain-specific network, the network domain specified for the +- For a domain-specific Network, the Network domain specified for the domain is used. If none is specified, the system looks for a value in the zone and global configuration, in that order. -- For a zone-specific network, the network domain specified for the +- For a zone-specific Network, the Network domain specified for the zone is used. If none is specified, the system looks for a value in the global configuration. +Managing log files +------------------ + +The log files are located in `/var/log/cloudstack`. This directory has the +following subdirectories: + +- `management` for the Management Server +- `usage` for the Usage Server +- `agent` for the Agent for KVM hosts + +CloudStack uses log4j2 to manage log files. The log4j2 configuration file +is located in the corresponding subdirectories in the `/etc/cloudstack/` +directory and is named `log4j-cloud.xml`. + +By default, cloudstack uses `TimeBasedTriggeringPolicy` which rolls over +the log file every day and are kept indefinitely. The log files are +compressed and archived in the same directory. + +Over time, the logs can fill up the entire disk space. To avoid this, you can +update the log4j-cloud.xml file to change the log file rollover and retention +policy. You can change the rollover policy to `SizeBasedTriggeringPolicy` +and set the maximum size of the log file. You can also set the maximum number +of archived log files to keep. + +For example, to change the rollover policy for `management-server.log` to +`SizeBasedTriggeringPolicy` and set the maximum size of the log file to +100MB and keep the maximum of 15 archived log files, you can update the +`log4j-cloud.xml` file as follows: + +.. code-block:: diff + + - + + + + + + + - + + + + + + + +You can also checkout some configuration recipes from the log4j2 documentation +`here `_. + Stopping and Restarting the Management Server --------------------------------------------------- @@ -539,3 +609,53 @@ To start the Management Server: # service cloudstack-management start + +Management Server Statistics and Peers +-------------------------------------- + +Administrators are able to view the statistics and peers information of management server. + +#. Log in to the CloudStack UI as administrator + +#. In the left navigation bar, click Infrastructure. + +#. Click "Management servers", all management servers are listed. + +|management-servers-list.png| + +#. Click the management server you'd like to view. The statistics of the management server are displayed. + +|management-server-statistics.png| + +#. Navigate to the "Peers" tab. The peers of the management servers are listed + +|management-server-peers.png| + + +Global settings for management servers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cssclass:: table-striped table-bordered table-hover + +======================================= ======================== +Configuration Description +======================================= ======================== +management.server.stats.interval Time interval in seconds, for management servers stats collection. Set to <= 0 to disable management servers stats. Default value is 60 +cluster.heartbeat.interval Interval (in milliseconds) to check for the heart beat between management server nodes. Default value is 1500 +cluster.heartbeat.threshold Threshold (in milliseconds) before self-fence the management server. The threshold should be larger than management.server.stats.interval. Default value is 150000 +======================================= ======================== + +.. note:: + - Every 60 seconds (configurable via management.server.stats.interval setting) each management server collects its statistics and publishes to all other management server peers. When other management server receives the published stats, it will set the peer state (owner is the receiver and peer is the sender) to Up. + - Every 1.5 seconds (configurable via cluster.heartbeat.interval), each management server writes heartbeat to CloudStack database, and check the stats of other management servers. + - If in the past 150 seconds (configurable via cluster.heartbeat.threshold), a management server does not write heartbeat and its peer states, its state and peer states will be set to Down by other management servers. + - In case a management server cannot write heartbeat to the database due to connection issue to the database, the host is set to Down state by other management server, when the database connection is restored, the management server will perform self-fencing and exit with code 219. + +.. |management-servers-list.png| image:: /_static/images/management-servers-list.png + :alt: List of management servers + +.. |management-server-statistics.png| image:: /_static/images/management-server-statistics.png + :alt: Details of management server + +.. |management-server-peers.png| image:: /_static/images/management-server-peers.png + :alt: List of management server peers diff --git a/source/adminguide/nas_plugin.rst b/source/adminguide/nas_plugin.rst new file mode 100644 index 0000000000..1c7b892e49 --- /dev/null +++ b/source/adminguide/nas_plugin.rst @@ -0,0 +1,156 @@ +.. 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. + +.. _NAS Backup and Recovery Plugin: + +NAS Backup and Recovery Plugin +============================== + +About the NAS Backup and Recovery Plugin +---------------------------------------- + +The NAS Backup and Recovery Plugin provider simple B&R operations for KVM +instances to any shared storage (NAS). It is based on `libvirt push backup mode +`_ +to take full instance backups (qcow2) and requires libvirt-7.2.0 and QEMU-4.2, +or high versions on the KVM hosts. + +Currently, only backup of VMs from the NFS, CEPH, File-based Shared Mountpoint +and Local Storage based Primary Storage are tested to work. All other Primary Storages +are not tested, backups on them may not work. + +The NAS B&R plugin requires admin to first add backup repositories which are +network-attached storage (shared storage). It supports NFS, CIFS/Samba and CephFS. + +When initiating B&R operations on KVM instance, the assigned backup offering +is used to infer backup repository (NAS) details which are then used to mount +the shared storage temporarily on the KVM host to perform instance backup/restore +disks operations. This also requires that admin installs NAS-storage specific +utilities on the KVM hosts such as nfs-utils/nfs-common, ceph-common and cifs-utils. + +Consider the following mount, typically performed on a KVM/Linux host to mount storage: + + mount -t -o
+ +Some examples for variety of shared storage can be: + + mount -t nfs 10.10.1.10:/export /target -o vers=4.2,defaults + + mount -t ceph 10.10.1.10,10.10.1.11,10.10.1.12:/ /target -o name=user,secret=xyz,defaults + +The backup repository is designed to accept these parameters (type, address and +mount options) as configurations to be used to execute mount operations such as +illustrated above. + +With 'nas' B&R plugin enabled, after a backup repositories are added, root +admins can create new backup offerings by selecting the zone and the backup +repository. These backup offerings are then assigned and used with KVM instances +to perform support B&R actions and operations. + +Using the NAS Backup and Recovery Plugin +---------------------------------------- +To use the NAS Backup and Recovery Plugin, the Backup and Recovery framework needs to be enabled first. Then the backup plugin 'nas' needs to be enabled on either the global or zone settings. + +================================= ======================== +Configuration Value +================================= ======================== +backup.framework.enabled true +backup.framework.provider.plugin nas +================================= ======================== + +Once the above two configurations are set, restart the cloudstack-management service. After restart check the Settings of the Zone where you want to enable NAS backups - make sure that the "backup.framework.enabled"="true" on the Setting tab of the Zone. Once this is done, we can add the backup repository for the 'nas' Backup and Recovery plugin. +Navigate to the Infrastructure -> Backup Repository. Click on 'Add Backup Repository' and fill the form. + +=================== ======================== +Field Value +=================== ======================== +Name A suitable name to represent the Backup Repository +Address URL, in case of NFS :/path +Type NFS / CIFS / CEPH +Mount options Any mount point options to be passed while mounting this storage on the hypervisor. +Zone The zone in CloudStack with which this Backup Repository must be associated. +=================== ======================== + +.. image:: /_static/images/B&R-Backup-Repository.png + :align: center + :alt: NAS Backup repository + +Pay attention to the "Name" given to this repository, as you will have to specify this in the "External ID" field when creating Backup Offerings (Importing backup offering) + +Once the Backup Repository is created, we need to add a Backup Offering, in this plugin the Backup offering is a placeholder to associate an instance to a Backup Repository. While creating the Backup Offering, select the desired Backup Repository. Associate the Backup Offering on an instance to create an Adhoc or scheduled backup. + +For the "External ID", please specify the name of the previously created backup repository. + +.. image:: /_static/images/B&R-Backup-Offerings.png + :align: center + :alt: NAS Backup offerings + +After this has been done, you can go to any Instance view and there will be buttons available for either ad-hoc backup or a scheduled backup of the VM + +Quiesce (Filesystem Freeze and Thaw) +------------------------------------ + +Users can set quiesce to true while creating a backup or a backup schedule. +When a backup is initiated with quiesce enabled, CloudStack uses QEMU guest agent +to freeze the filesystem before starting backup. This operation flushes all dirty +filesystem buffers to disk and quiesces new writes. The filesystem is then thawed +immediately after the backup process starts, keeping the freezing window very short. + +|NASB&R-quiesceInstance.png| + +This enhancement brings the NAS backup plugin from crash-consistent backups closer to +application-consistent backups. + +Points to note: + +#. The feature requires qemu-guest-agent to be installed and running on the guest instance. +#. This method does not capture the memory state of the guest. Any data held in application memory + that hasn’t been flushed to disk prior to the filesystem freeze will not be captured. +#. For fully application-consistent backups, guest applications must implement pre-freeze hooks + to flush their internal state to disk before the filesystem is frozen. + +Support Information and Limitation +---------------------------------- + +The NAS B&R plugin has been tested with EL8, EL9, Ubuntu 22.04 and 24.04. Older +KVM distros such as EL7, Ubuntu 20.04 etc may not work due to libvirt/qemu +version requirements. Other supported KVM-distros are not tested but may work +such as OpenSUSE 15, Debian 11 and Debian 12. + +Instance backups are full disk backups and limited by libvirt's ability to +initiate and handle backup. All such backups are exported and stored in qcow2 +format only. Due to this, restore operation for volumes of type raw, on CEPH based +primary storage pools, are converted from qcow2 to raw format using qemu-img convert. +Restore operation for volumes of type qcow2, on NFS and Local Storage based primary +storage pools, does not need such conversion as these can be directly copied. + +For running instances, their disks (of any format/storage type) are backed up by +libvirtd's push based efficient-backup mechanism exported as qcow2 disks on the +backup repository. + +For stopped instances, `qemu-img` is used to convert and export full-disk backup +in qcow2 format to the backup repository. + +For restore operations, the KVM instance must be stopped in CloudStack. +Currently, only volume(s) restoration is supported only to NFS, CEPH, File-based Shared Mountpoint +and Local Storage based primary storage pools, and restored volumes are fully backed disks (i.e. +not using any backing template file). + +Backup and restore operations are not fully supported for CKS cluster instances and should +be avoided. + +.. |NASB&R-quiesceInstance.png| image:: /_static/images/NASB&R-quiesceInstance.png + :alt: Quiesce option while creating backups. + :width: 400 px diff --git a/source/adminguide/networker_plugin.rst b/source/adminguide/networker_plugin.rst new file mode 100644 index 0000000000..9864d78f35 --- /dev/null +++ b/source/adminguide/networker_plugin.rst @@ -0,0 +1,214 @@ +.. 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. + +.. _DELL EMC Networker Backup and Recovery Plugin: + +DELL EMC Networker Backup and Recovery Plugin +============================================= + +About the DELL EMC Networker Backup and Recovery Plugin +--------------------------------------------------------- + +Administrators must make sure that the following requirements and prerequisites are met in order for the plugin +to work as expected. + +EMC Networker Server + +#. A fairly recent .rpm or .deb Linux distribution that is supported by DELL EMC Networker for the installed version. +#. Network connectivity between the Cloudstack Management Servers in your zone and DELL EMC Networker Server +#. Administration access to the DELL EMC Networker management consoles +#. Unrestricted access to API port (running default at: 9090/tcp) +#. A proper timezone set. Identical to the Hypervisors and Management server +#. Proper DNS resolution of the Clients + +KVM Hypervisor(s) + +#. A BASH shell at minimum version 4.4.19 +#. DELL EMC Networker client must be installed and in running state +#. Hypervisor must be associated with the DELL EMC Networker server as CLIENT +#. DELL EMC Networker can connect and verify certificates to the KVM Client +#. A Hypervisor must be in UP and ENABLED state and resource state respectively in order to be able to get backups + for the Instances running. +#. A proper timezone set. Identical to the EMC Networker Server and Management server +#. Proper DNS resolution of the EMC Networker server + +Instances + +#. It is HIGHLY recommended to run qemu-guest-agent on the Machines you are planning to backup. +#. There has been no testing regarding KVM Primary Storage Snapshots and possible problems with EMC DELL Networker plugin +#. In case you are using KVM Primary Storage Snapshots, you have EMC Networker and you want to proceed with the + installation of this plugin proceed with extreme caution. + +General Concepts + +#. DELL EMC Networker POLICIES are presented as Backup Provider Offerings to Cloudstack. + At that level we can set the Protection Period (aka Expiration) to specify when backups + will expire. Restricted data zones can also be defined in POLICIES to create fine grain permissions. +#. As per EMC Networker Glossary and design those POLICIES are not actually used. They act as a placeholder + for the backup offerings and the retention policies. +#. DELL EMC Networker has no ability to initiate backup tasks for KVM Instances at the moment. + The implementation is based on manual save sets initiated by the Cloudstack Networker plugin. +#. The tag -CSBKP- in the comment of the POLICY indicates that this policy is available to Cloudstack + Other POLICIES used in your infrastructure will not be visible inside Cloudstack. It is recommended to create + brand new POLICIES dedicated to Cloudstack and settings the Protection Periods to match the backup plan retention + you wish to enable for each of the offerings. +#. For each KVM Cluster you have, a relevant dummy client must be created in the DELL EMC Networker. This is used as a + placeholder for being able to backup and restore your Instances from all hosts within the cluster. +#. Cross cluster restores are indirectly supported by restoring to the original cluster and then migrating the Virtual + Machine to the destination cluster. +#. Any manual KVM backup you initiate (from the command line) will be registered in Cloudstack automatically. + You need to use the client scripts and pass the proper parameters to do so. +#. Any backup you expire/remove from the DELL EMC Networker side will be unregistered in Cloudstack automatically. + +Installing DELL EMC Networker Backup and Recovery Plugin +-------------------------------------------------------- + +The B&R Networker plugin has been designed and implemented taking in mind the particularities of the DELL EMC Networker +backup suite. It has been developed and tested against 19.4.0.6 and the minimum supported version is 9.2. + +The installation and configuration of the DELL EMC Networker is out of scope and it is assumed that it has been properly +performed in advance. Kindly make sure that DNS resolution, Timezones and system clocks are set/synced for KVM Hypervisors, +Cloudstack Management Servers and DELL EMC Networker Server. Do not forget to perform your staging actions (if any) +before the savesets expire. + +Depending on your topology, network bandwidth, backend storage speeds, number of customer Instances you should carefully plan, +design and implement the Storage volumes, media pools. If you have multiple Instances that your customers want to be processed +at the same time (e.g Friday night, end of business day in your timezone) this can easily overwhelm your resources since +the backups are initiated outside DELL EMC Networker. + +A brief Outline of the prerequisite steps is provided. + +#. Install / Configure DELL EMC Networker Server (if you don't already have one running) +#. Set timezone and enable ntp/chrony +#. Set proper DNS Servers or alternatively add all KVM Hypervisors to /etc/hosts +#. Install DELL EMC Networker client and extended client packages to all Hypervisors +#. Add all KVM Hypervisors as Clients in the EMC Networker (Traditional Backup) +#. Create a USER in EMC DELL Networker with privileges to create/delete backups + + +Creating POLICIES on the Networker Side +---------------------------------------- + +#. In the DELL EMC Networker Management Console create the desired POLICIES including the -CSBKP- tag in the + comment section. + + |BnR-Networker-Policy.jpg| + +#. After finishing with the POLICIES you will end up with something like this + + |BnR-Networker-Policies.jpg| + +#. Create a dedicated Media Pool (recommended but not required). + + |BnR-Networker-MediaPool-General.jpg| + +#. Set the configuration values according to your environment, equipment, needs and constraints. + + |BnR-Networker-MediaPool-Configuration.jpg| + +#. In Selection Criteria tab you can select the device(s) associated with that Media Pool. A use of a deduplication + capable storage device (such as DataDomain) is recommended. + +#. Check your cluster name (e.g from cloud monkey). + Please note that cluster name case sensitivity matters. + + |BnR-Networker-clustername.jpg| + +#. Create relevant DNS entries for all your KVM clusters in your nameservers or add it in the /etc/hosts of your + DELL EMC NETWORKER server. The IP addresses can be anything you want but must be present. + +#. Create a client representing the cluster on the EMC Networker Side + + |BnR-Networker-Cluster-Client-General.jpg| + |BnR-Networker-Cluster-Client-Globals1.jpg| + +#. Include all the users and hypervisor hosts on the Global (2 of 2) page + + |BnR-Networker-Cluster-Client-Globals2.jpg| + +#. Your final client configuration should have all KVM hosts and Clusters defined. + + |BnR-Networker-Cluster-Clients-overview.jpg| + + +Connecting CloudStack to DELL EMC Networker +---------------------------------------------- + +Before enabling DELL EMC Networker make sure that the user account Cloudstack uses to connect to your KVM Hypervisors +can execute via SUDO and with no required password the following binary from EMC Networker: + +#. /usr/sbin/recover + +Also make sure that the user account Cloudstack uses to connect to your KVM Hypervisors is member of the libvirt group. + +Updating the global settings listed below will allow you to start the importing of the backup offerings to Cloudstack. + +Plug-in specific settings: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(all settings can be global or per-zone) + +.. cssclass:: table-striped table-bordered table-hover + +======================================== ============================================================================= +Configuration Description +======================================== ============================================================================= +backup.plugin.networker.url DELL EMC Networker server URL. Default: https://localhost:9090/nwrestapi/v3 +backup.plugin.networker.username DELL EMC Networker server username. Default: administrator +backup.plugin.networker.password DELL EMC Networker server password. Default: password +backup.plugin.networker.pool DELL EMC Networker Media Pool. Default: Default +backup.plugin.networker.validate.ssl Whether to validate API server (SSL/TLS) connection. Default: false +backup.plugin.networker.request.timeout DELL EMC Networker API request timeout in seconds. Default: 300 +backup.plugin.networker.client.verbosity DELL EMC Networker Client verbosity: Default: false +======================================== ============================================================================= + + +Client Logs and Verbosity +------------------------- + +The default location for the logs is under /nsr/logs/cloudstack for each KVM Hypervisor. You should be familiar with that +location from your usual Networker debugging. By setting the verbosity to true you will have comprehensive step by step +list of all the actions and failures. For production use and when not debugging it is recommended to not use verbose logging. + +It is also recommended to add that location to your regular log rotating policy. + + +.. |BnR-Networker-Policy.jpg| image:: /_static/images/BnR-Networker-Policy.jpg + :alt: Create Networker Policy. + :width: 350 px +.. |BnR-Networker-Policies.jpg| image:: /_static/images/BnR-Networker-Policies.jpg + :alt: Networker Policies. + :width: 400 px +.. |BnR-Networker-MediaPool-General.jpg| image:: /_static/images/BnR-Networker-MediaPool-General.jpg + :alt: Media Pool General Properties. + :width: 350 px +.. |BnR-Networker-MediaPool-Configuration.jpg| image:: /_static/images/BnR-Networker-MediaPool-Configuration.jpg + :alt: Media Pool Configuration Properties. + :width: 350 px +.. |BnR-Networker-clustername.jpg| image:: /_static/images/BnR-Networker-clustername.jpg + :alt: Cluster Client CMK. + :width: 400 px +.. |BnR-Networker-Cluster-Client-General.jpg| image:: /_static/images/BnR-Networker-Cluster-Client-General.jpg + :alt: Cluster Client Creation. + :width: 350 px +.. |BnR-Networker-Cluster-Client-Globals1.jpg| image:: /_static/images/BnR-Networker-Cluster-Client-Globals1.jpg + :alt: Cluster client Globals (1 of 2). + :width: 350 px +.. |BnR-Networker-Cluster-Client-Globals2.jpg| image:: /_static/images/BnR-Networker-Cluster-Client-Globals2.jpg + :alt: Cluster client Globals (2 of 2). + :width: 350 px +.. |BnR-Networker-Cluster-Clients-overview.jpg| image:: /_static/images/BnR-Networker-Cluster-Clients-overview.jpg + :alt: Cluster Clients Overview. + :width: 300 px diff --git a/source/adminguide/networking.rst b/source/adminguide/networking.rst index cd96aeb963..f0cf3c1de0 100644 --- a/source/adminguide/networking.rst +++ b/source/adminguide/networking.rst @@ -48,7 +48,7 @@ or isolated. Isolated Networks ~~~~~~~~~~~~~~~~~ -An isolated network can be accessed only by virtual machines of a single +An isolated network can be accessed only by Instances of a single account. Isolated networks have the following properties. - Resources such as VLAN are allocated and garbage collected @@ -66,12 +66,14 @@ For more information, see `“Configure Guest Traffic in an Advanced Zone” Shared Networks ~~~~~~~~~~~~~~~ -A shared network can be accessed by virtual machines that belong to many +A shared network can be accessed by Instances that belong to many different accounts. Network Isolation on shared networks is accomplished by using techniques such as security groups, which is supported only in Basic zones or Advanced Zones with Security Groups. -- Shared Networks are created by the administrator +- Shared Networks are created by the end users or the administrator. Network offerings + which allow the network creator to specify a VLAN can only be created + by the root admins. - Shared Networks can be designated to a certain domain @@ -84,8 +86,10 @@ Basic zones or Advanced Zones with Security Groups. - Source NAT per zone is not supported in Shared Network when the service provider is virtual router. However, Source NAT per account - is supported. For information, see `“Configuring a Shared Guest - Network” `_. + is supported. + +For more information, see `“Configuring a Shared Guest Network” +`_. L2 (Layer 2) Networks @@ -100,9 +104,9 @@ IP addresses. which allow the network creator to specify a VLAN can only be created by the root admins. -- CloudStack does not assign IP addresses to VMs. +- CloudStack does not assign IP addresses to instances. -- Userdata and metadata can be passed to the VM using a config drive +- User Data and metadata can be passed to the instance using a config drive (which must be enabled in the network service offering) Example GUI dialog box (for a regular user account) is shown below: @@ -115,8 +119,8 @@ Runtime Allocation of Virtual Network Resources When you define a new virtual network, all your settings for that network are stored in CloudStack. The actual network resources are -activated only when the first virtual machine starts in the network. -When all virtual machines have left the virtual network, the network +activated only when the first Instance starts in the network. +When all Instances have left the virtual network, the network resources are garbage collected so they can be allocated again. This helps to conserve network resources. @@ -152,28 +156,28 @@ offering. .. cssclass:: table-striped table-bordered table-hover -+----------------------+-----------+------------+----------+-------------+-------------+ -| | Virtual | Citrix | Juniper | F5 BigIP | Host based | -| | Router | NetScaler | SRX | | (KVM/Xen) | -+======================+===========+============+==========+=============+=============+ -| Remote Access VPN | Yes | No | No | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| DNS/DHCP/User Data | Yes | No | No | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Firewall | Yes | No | Yes | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Load Balancing | Yes | Yes | No | Yes | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Elastic IP | No | Yes | No | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Elastic LB | No | Yes | No | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Source NAT | Yes | No | Yes | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Static NAT | Yes | Yes | Yes | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ -| Port Forwarding | Yes | No | Yes | No | No | -+----------------------+-----------+------------+----------+-------------+-------------+ ++----------------------+-----------+------------+-------------+ +| | Virtual | Citrix | Host based | +| | Router | NetScaler | (KVM/Xen) | ++======================+===========+============+=============+ +| Remote Access VPN | Yes | No | No | ++----------------------+-----------+------------+-------------+ +| DNS/DHCP/User Data | Yes | No | No | ++----------------------+-----------+------------+-------------+ +| Firewall | Yes | No | No | ++----------------------+-----------+------------+-------------+ +| Load Balancing | Yes | Yes | No | ++----------------------+-----------+------------+-------------+ +| Elastic IP | No | Yes | No | ++----------------------+-----------+------------+-------------+ +| Elastic LB | No | Yes | No | ++----------------------+-----------+------------+-------------+ +| Source NAT | Yes | No | No | ++----------------------+-----------+------------+-------------+ +| Static NAT | Yes | Yes | No | ++----------------------+-----------+------------+-------------+ +| Port Forwarding | Yes | No | No | ++----------------------+-----------+------------+-------------+ Network Offerings @@ -202,12 +206,12 @@ A network offering is a named set of network services, such as: - VPN - (Optional) Name one of several available providers to use for a given - service, such as Juniper for the firewall + service - (Optional) Network tag to specify which physical network to use -When creating a new VM, the user chooses one of the available network -offerings, and that determines which network services the VM can use. +When creating a new instance, the user chooses one of the available network +offerings, and that determines which network services the instance can use. The CloudStack administrator can create any number of custom network offerings, in addition to the default network offerings provided by @@ -267,14 +271,14 @@ To create a network offering: - **Persistent**. Indicate whether the guest network is persistent or not. The network that you can provision without having to - deploy a VM on it is termed persistent network. For more + deploy an instance on it is termed persistent network. For more information, see `“Persistent Networks” `_. - - **Specify VLAN**. (Isolated guest networks only) Indicate whether + - **Specify VLAN**. Indicate whether a VLAN could be specified when this offering is used. If you select this option and later use this network offering while - creating a VPC tier or an isolated network, you will be able to + creating a VPC Network Tier or an isolated network, you will be able to specify a VLAN ID for the network you create. - **VPC**. This option indicate whether the guest network is Virtual @@ -284,9 +288,19 @@ To create a network offering: For more information on VPCs, see `“About Virtual Private Clouds” `_. + - **Network mode**. This option indicates the mode with which the network will operate. + Valid options are NATTED (default) or ROUTED. This applies on isolated networks only. + For more information on Network mode, see `“About Network + Mode” `_. + + - **Routing mode**. This option indicates the routing mode for the network offering. + Supported types are: Static or Dynamic. + For more information on Routing mode, see `“About Routing + Mode” `_. + - **Promiscuous Mode**. Applicable for guest networks on VMware hypervisor only. It accepts the following values for desired behaviour of the network elements: - *Reject* - The switch drops any outbound frame from a virtual machine adapter with a source MAC address that is different from the one in the .vmx configuration file. + *Reject* - The switch drops any outbound frame from an Instance adapter with a source MAC address that is different from the one in the .vmx configuration file. *Accept* - The switch does not perform filtering, and permits all outbound frames. @@ -294,7 +308,7 @@ To create a network offering: - **Forged Transmits**. Applicable for guest networks on VMware hypervisor only. It accepts the following values for desired behaviour of the network elements: - *Reject* - The switch drops any outbound frame from a virtual machine adapter with a source MAC address that is different from the one in the .vmx configuration file. + *Reject* - The switch drops any outbound frame from an Instance adapter with a source MAC address that is different from the one in the .vmx configuration file. *Accept* - The switch does not perform filtering, and permits all outbound frames. @@ -302,11 +316,11 @@ To create a network offering: - **MAC Address Changes**. Applicable for guest networks on VMware hypervisor only. It accepts the following values for desired behaviour of the network elements: - *Reject* - If the guest OS changes the effective MAC address of the virtual machine to a value that is different from the MAC address of the VM network adapter (set in the .vmx configuration file), the switch drops all inbound frames to the adapter. + *Reject* - If the guest OS changes the effective MAC address of the Instance to a value that is different from the MAC address of the instance network adapter (set in the .vmx configuration file), the switch drops all inbound frames to the adapter. - If the guest OS changes the effective MAC address of the virtual machine back to the MAC address of the VM network adapter, the virtual machine receives frames again. + If the guest OS changes the effective MAC address of the Instance back to the MAC address of the instance network adapter, the Instance receives frames again. - *Accept* - If the guest OS changes the effective MAC address of the virtual machine to a value that is different from the MAC address of the VM network adapter, the switch allows frames to the new address to pass. + *Accept* - If the guest OS changes the effective MAC address of the Instance to a value that is different from the MAC address of the instance network adapter, the switch allows frames to the new address to pass. *None* - Default to value from global setting - ``network.mac.address.changes``. @@ -353,8 +367,8 @@ To create a network offering: been configured in the cloud. VPN For more information, see `“Remote Access Supported Not Supported VPN” `_. - User Data For more information, see `“User Data and Meta Not Supported Supported - Data” `_. + User Data For more information, see `“User Data and Metadata Not Supported Supported + ” `_. Network ACL For more information, see `“Configuring Network Access Control List Supported Not Supported ” `_. Security Groups For more information, see `“Adding a Security Not Supported Supported @@ -394,6 +408,8 @@ To create a network offering: its maximum capacity, the device will not be allocated to a new account. +.. not sure how this works after deprecation of Juniper devices + - **Mode**: You can select either Inline mode or Side by Side mode: - **Inline mode**: Supported only for Juniper SRX firewall and BigF5 @@ -410,7 +426,7 @@ To create a network offering: and therefore, is exposed to the public network. - **Associate Public IP**: Select this option if you want to assign - a public IP address to the VMs deployed in the guest network. This + a public IP address to the instances deployed in the guest network. This option is available only if - Guest network is shared. @@ -426,12 +442,18 @@ To create a network offering: if you want to use two virtual routers in the network for uninterrupted connection: one operating as the primary virtual router and the other as the backup. The primary virtual router - receives requests from and sends responses to the user’s VM. The + receives requests from and sends responses to the user’s instance. The backup virtual router is activated only when the primary is down. After the failover, the backup becomes the primary virtual router. CloudStack deploys the routers on different hosts to ensure reliability if one host is down. + - **Supports instance auto scaling**: Indicate whether instance autoscaling feature + is supported. It is available only when Virtual Router or Netscaler + is selected as the Load Balancer provider. For more information on + instance autoscaling using Virtual Router, see `“Configuring AutoScale + with using CloudStack Virtual Router” `_. + - **Conserve mode**: Indicate whether to use conserve mode. In this mode, network resources are allocated only when the first virtual machine starts in the network. When conservative mode is off, the diff --git a/source/adminguide/networking/advanced_zone_config.rst b/source/adminguide/networking/advanced_zone_config.rst index 68b492919e..558c001272 100644 --- a/source/adminguide/networking/advanced_zone_config.rst +++ b/source/adminguide/networking/advanced_zone_config.rst @@ -19,7 +19,7 @@ Advanced Zone Physical Network Configuration -------------------------------------------- Within a zone that uses advanced networking, you need to tell the -Management Server how the physical network is set up to carry different +Management Server how the physical Network is set up to carry different kinds of traffic in isolation. @@ -27,42 +27,62 @@ Configure Guest Traffic in an Advanced Zone ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These steps assume you have already logged in to the CloudStack UI. To -configure the base guest network: +configure the base guest Network: #. In the left navigation, choose Network. -#. Click Add network. +#. Click Add Network. - The Add guest network window is displayed: + The Add guest Network window is displayed: |addguestnetwork.png| -#. Provide the following information for creating an isolated network: +#. Provide the following information for creating an isolated Network: - - **Name**: The name of the network. This will be user-visible + - **Name**: The name of the Network. This will be User-visible - - **Description**: The description of the network. This will be - user-visible + - **Description**: The description of the Network. This will be + User-visible - - **Zone**: The zone in which you are configuring the guest network. + - **Zone**: The zone in which you are configuring the guest Network. - **Network offering**: If the administrator has configured multiple - network offerings, select the one you want to use for this network + Network offerings, select the one you want to use for this Network - - **External Id**: ID of the network in an external system. + - **Public MTU**: The MTU that will be configured on the public interfaces + of the Network's VR. + **NOTE:** This will not be considered for VPC Network Tiers, as the + public MTU defined at the VPC Network creation level will be considered + + - **Private MTU**: The MTU that will configured on the private interface(s) + of the Network's VR + + - **External Id**: ID of the Network in an external system. - - **Gateway**: The gateway that the guests instances will use. + - **Gateway**: The gateway that the guests Instances will use. - - **Netmask**: The netmask in use on the subnet the guest instances + - **Netmask**: The netmask in use on the subnet the Guest Instances will use. - - **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 + - **CIDR Size**: The cidrsize of the subnet the Guest Instances will use. Available only when the selected Network offering supports ROUTED mode. + + - **DNS**: A set of custom DNS that will be used by the guest Network. If not provided then DNS specified for the zone will be used. Available only when the selected Network offering supports DNS service. + + - **IPv6 DNS**: A set of custom IPv6 DNS that will be used by the guest Network. If not provided then IPv6 DNS specified for the zone will be used. Available only when the selected Network offering is IPv6 enabled and supports DNS service. + + - **IPv4 address for the VR in this Network**: The source NAT address or primary public Network address to use by the guest Network. If not provided then a random address from the available pool of addresses will be used. + + - **Network Domain**: A custom DNS suffix at the level of a Network. If you + want to assign a special domain name to the Guest Instance Network, specify a DNS suffix. #. Click OK. +.. note:: + * In security groups-enabled Advanced zones and Basic zones, creation of VPC and isolated Networks are not supported. + * MTU options will be shown in the UI and considered only when zone configuration - `allow.end.users.to.specify.vr.mtu` is set to true. Maximum allowed values for public and private MTU can be controlled by zone-level configurations, `vr.public.interface.max.mtu` and `vr.private.interface.max.mtu` respectively. + * We can configure a zone with multiple Physical Networks having guest traffic type. In such zones, we need to tag the additional Physical networks. We must have one Physical Network that is not tagged for isolated/L2 network offerings not configured with any tags. For example the default network offerings. Configure Public Traffic in an Advanced Zone ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -74,83 +94,113 @@ one range of IP addresses for Internet traffic. Configuring a Shared Guest Network ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Log in to the CloudStack UI as administrator. +#. Log in to the CloudStack UI as administrator or an end User. + +#. In the left navigation, choose Network. -#. In the left navigation, choose Infrastructure. +#. Click the Guest Networks tab -#. On Zones, click View More. +#. Click the Add Network icon. -#. Click the zone to which you want to add a guest network. +#. Click the Shared tab. -#. Click the Physical Network tab. + The Add guest Network window is displayed. -#. Click the physical network you want to work with. + |addsharednetwork.png| -#. On the Guest node of the diagram, click Configure. +#. Specify the following: -#. Click the Network tab. + - **Name**: The name of the Network. This will be visible to the User. -#. Click Add guest network. + - **Description**: The short description of the Network that can be + displayed to Users. - The Add guest network window is displayed. + - **Zone**: The zone for the Network. -#. Specify the following: + - **Physical Network**: The physical Network ID the Network belongs to. - - **Name**: The name of the network. This will be visible to the user. + - **VLAN ID**: (Administrators only) The unique ID of the VLAN. - - **Description**: The short description of the network that can be - displayed to users. + - **Secondary VLAN Type**: (Administrators only) The isolation private + VLAN type for this Network - - **VLAN ID**: The unique ID of the VLAN. + - **Secondary VLAN ID**: (Administrators only) The unique ID of the + Secondary Isolated VLAN. - - **Isolated VLAN ID**: The unique ID of the Secondary Isolated - VLAN. + - **Bypass VLAN id/range overlap**: (Administrators only) When true + bypasses VLAN id/range overlap check during Network creation for + shared and L2 Networks - **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 + 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 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 + - **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 + - **Project**: The project for which the guest Network is being created for. You must specify the domain the project belongs to. - - **All**: The guest network is available for all the domains, - account, projects within the selected zone. + - **All**: (Administrators only) The guest Network is available + for all the domains, Account, projects within the selected zone. - **Network Offering**: If the administrator has configured multiple - network offerings, select the one you want to use for this - network. + Network offerings, select the one you want to use for this + Network. + + - **Public MTU**: The MTU that will be configured on the public interfaces + of the Network's VR. This MTU will considered for redundant VRs + + - **Private MTU**: The MTU that will configured on the private interface(s) + of the Network's VR + + - **Associated Network**: The L2 or Isolated Network this Network is + associated to. This Network will use same VLAN as associated Network. + This will be visible if Network offering has specifyvlan is false. - **Gateway**: The gateway that the guests should use. - **Netmask**: The netmask in use on the subnet the guests will use. - **IP Range**: A range of IP addresses that are accessible from the - Internet and are assigned to the guest VMs. + Internet and are assigned to the Guest Instances. + + - **DNS**: A set of custom DNS that will be used by the Network. If not provided then DNS specified for the zone will be used. Available only when the selected Network offering supports DNS service. If one NIC is used, these IPs should be in the same CIDR in the case of IPv6. - - **IPv6 CIDR**: The network prefix that defines the guest network + - **IPv6 CIDR**: The Network prefix that defines the guest Network subnet. This is the CIDR that describes the IPv6 addresses in use - in the guest networks in this zone. To allot IP addresses from + in the guest Networks in this zone. To allot IP addresses from within a particular address block, enter a CIDR. - - **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. + - **IPv6 DNS**: A set of custom IPv6 DNS that will be used by the Network. If not provided then IPv6 DNS specified for the zone will be used. Available only when the selected Network offering supports DNS service. + + - **Network Domain**: A custom DNS suffix at the level of a Network. + If you want to assign a special domain name to the Guest Instance + Network, specify a DNS suffix. #. Click OK to confirm. + .. note:: + * End users (not administrator) can only use the Network + offerings with specifyvlan is false. Please create a Network offering + with specifyvlan is false to enable this for end users. See + `“Creating a New Network Offering” + `_. + * MTU options will be shown in the UI and considered only when zone configuration - `allow.end.users.to.specify.vr.mtu` is set to true. Maximum allowed values for public and private MTU can be controlled by zone-level configurations, `vr.public.interface.max.mtu` and `vr.private.interface.max.mtu` respectively. + .. |addguestnetwork.png| image:: /_static/images/add-guest-network.png - :alt: Add Guest network setup in a single zone. \ No newline at end of file + :alt: Add Guest network setup in a single zone. + +.. |addsharednetwork.png| image:: /_static/images/add-shared-network.png + :alt: Add Shared Guest Network. diff --git a/source/adminguide/networking/basic_zone_config.rst b/source/adminguide/networking/basic_zone_config.rst index a1ba26c5df..692d0111e8 100644 --- a/source/adminguide/networking/basic_zone_config.rst +++ b/source/adminguide/networking/basic_zone_config.rst @@ -20,5 +20,5 @@ Basic Zone Physical Network Configuration In a basic network, configuring the physical network is fairly straightforward. You only need to configure one guest network to carry -traffic that is generated by guest VMs. When you first add a zone to +traffic that is generated by Guest Instances. When you first add a zone to CloudStack, you set up the guest network through the Add Zone screens. \ No newline at end of file diff --git a/source/adminguide/networking/dns_and_dhcp.rst b/source/adminguide/networking/dns_and_dhcp.rst index c84cffabe7..928c151607 100644 --- a/source/adminguide/networking/dns_and_dhcp.rst +++ b/source/adminguide/networking/dns_and_dhcp.rst @@ -17,6 +17,13 @@ DNS and DHCP ------------ -The Virtual Router provides DNS and DHCP services to the guests. It -proxies DNS requests to the DNS server configured on the Availability -Zone. +The Virtual Router & ConfigDrive (since Apache CloudStack 4.20) provides +DNS and DHCP services to the guests. It proxies DNS requests to the DNS +server configured on the Availability Zone. + +.. note:: + In case of a network with ConfigDrive, adding/removing nic to/from an + instance or updating the ip address of a nic will not be reflected in the + instance if the instance is already running. To do so, run + `cloud-init clean --machine-id -s` to clean the machine id and seed data. + Then reboot the instance to apply the changes. \ No newline at end of file diff --git a/source/adminguide/networking/dynamic_static_routing.rst b/source/adminguide/networking/dynamic_static_routing.rst new file mode 100644 index 0000000000..701ab1dbc4 --- /dev/null +++ b/source/adminguide/networking/dynamic_static_routing.rst @@ -0,0 +1,290 @@ +.. 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. + + +Dynamic and Static Routing +----------------------------- + +For VMs on Isolated networks, the IP of VMs are not publicly accessible. +To access the VMs from the Internet, users need to create Load balancing rules, +Port Forwarding rules, enable Static NAT, or enable VPN. + +The IPv6 static routing feature has been introduced in Apache CloudStack 4.17.0.0, so that +users are able to access the IPv6 address of guest VMs on Isolated networks from the Internet or public network. +For more information, see `“IPv6 support for isolated networks and VPC Network Tiers” <../plugins/ipv6.html#isolated-network-and-vpc-network-tier>`_. + +From Apache CloudStack 4.20.0.0, users are able to create isolated networks and VPCs with ROUTED mode. + +- Manage IPv4 subnets for Zones (ROOT admin/operator only) +- Create Networks with Static Routing for IPv4 +- Manage IPv4 Routing Firewall for Networks +- Manage AS number and BPG peers for Dynamic Routing (ROOT admin only) +- Create Networks with Dynamic Routing for IPv4 and IPv6 + + +About Network Mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Network mode indicates the mode with which the isolated network or VPC will operate. +There are two valid options + +- NATTED. This is the default network mode of isolated networks. The VR of isolated networks and VPCs provides Source NAT services, as well as Static NAT, Load Balancer, Port Forwarding, VPN if the network offering supports. +- ROUTED. For isolated networks in ROUTED mode, the VR no longer supports Source NAT, Static NAT, Load Balancer, Port Forwarding and VPN. The supported services are DNS, DHCP, User data, Firewall (for isolated networks) and Network ACL (for VPC and VPC networks). + + +About Routing mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Routing mode indicates how routing will operate with the isolated networks with ROUTED network mode. +There are two valid options + +- Static. The operators need to add the static routes to the isolated networks or VPCs in the upstream router manually. +- Dynamic. The AS number will be automatically allocated, and BGP peer sessions will be set up automatically in the VR of the isolated networks or VPCs. The operators need to add the AS number ranges and BGP peers for each zone before creating network with Dynamic routing mode. + + +Manage IPv4 Subnets for Zone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Like IPv6 prefixes, operators need to configure the IPv4 subnets for zone, which will be eventually used by guest networks. + +Supported CloudStack APIs for operators to manage the IPv4 subnets for zone are: + +- **createIpv4SubnetForZone** : create an IPv4 subnet for zone +- **dedicateIpv4SubnetForZone** : dedicate an IPv4 subnet for zone to a domain or an account +- **deleteIpv4SubnetForZone** : delete an IPv4 subnet for zone +- **listIpv4SubnetsForZone** : list IPv4 subnets for zone +- **releaseIpv4SubnetForZone** : release a dedicated IPv4 subnet for zone from a domain or an account +- **updateIpv4SubnetForZone** : update an IPv4 subnet for zone + +Operators (root admins) can manage the IPv4 subnets for zone by navigating to Infrastructure -> Zones -> IPv4 Subnets +|manage-ipv4-subnets-for-zone.png| + + +Manage IPv4 Subnets for Guest Networks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unlike IPv6 (each isolated network with IPv6 support gets a /64 IPv6 network), operators need to manage IPv4 subnets for guest networks. +An IPv4 subnet for guest networks is created from its parent which is a IPv4 subnet for zone. + +There are some global settings which can be set for each account. See below + +.. cssclass:: table-striped table-bordered table-hover + +================================================= ======================== +Configuration Description +================================================= ======================== +routed.ipv4.network.cidr.auto.allocation.enabled Whether the auto-allocation of network CIDR for routed network is enabled or not. True by default. +routed.ipv4.network.max.cidr.size The maximum value of the cidr size for isolated networks in ROUTED mode +routed.ipv4.network.min.cidr.size The minimum value of the cidr size for isolated networks in ROUTED mode +routed.ipv4.vpc.max.cidr.size The maximum value of the cidr size for VPC in ROUTED mode +routed.ipv4.vpc.min.cidr.size The minimum value of the cidr size for VPC in ROUTED mode +================================================= ======================== + +Supported CloudStack APIs for operators to manage the IPv4 subnets for guest networks are: + +- **createIpv4SubnetForGuestNetwork** : create an IPv4 subnet for guest networks +- **deleteIpv4SubnetForGuestNetwork** : delete an IPv4 subnet for guest networks +- **listIpv4SubnetsForGuestNetwork** : list IPv4 subnets for guest networks + +Operators (root admins) can manage the IPv4 subnet by navigating to Network -> IPv4 Subnets +|manage-ipv4-subnets-for-networks.png| + + +Create Network and VPC Offering with ROUTED mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create network offering with ROUTED mode, see `“Creating a New Network Offering” `_. + +|routed-add-network-offering.png| + +To create VPC offering with ROUTED mode, see below + +|routed-add-vpc-offering.png| + + +Create Network with Static Routing for IPv4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a network with static routing, users need to navigate to Network -> Add Network -> Isolated, and + +- Choose a network offering with ROUTED mode and routing mode is Static +- Specify the gateway and netmask (available for ROOT admin only) +- OR, specify the cidrsize (available for all users) + +|routed-add-network-cidrsize.png| + +If cidrsize is specified, CloudStack will allocate an IPv4 subnet for guest network to the net network + +- Check if there is an IPv4 subnet with same CIDR size available, +- If not, and setting "routed.ipv4.network.cidr.auto.allocation.enabled" is true for account, allocate an IPv4 subnet for the new network, from the IPv4 subnet for zone which the account can access. +- Otherwise, the network creation fails. + +When the network is implemented, the Ipv4 routes are displayed in the network details page. + +|routed-ipv4-routes.png| + +.. note:: + For networks or VPCs with ipv4 static routing, the administrator needs to add upstream IPv4 routes once a network or VPC is successfully deployed. + + +Create Network with Static Routing for IPv6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The IPv6 static routing has been introduced in Apache CloudStack 4.17.0.0. +For more information, see `“IPv6 support for isolated networks and VPC Network Tiers” <../plugins/ipv6.html#isolated-network-and-vpc-network-tier>`_. + +Users can create network with static routing for both IPv4 and IPv6, if the network offering supports DualStack. + + +Manage IPv4 Routing Firewall +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users can manage the IPv4 Routing firewalls by navigating to Network -> Guest Networks -> choose a network -> IPv4 Routing Firewall + +|routed-ipv4-routing-firewall.png| + +Supported CloudStack APIs for operators to manage the IPv4 Routing firewall rules are: + +- **createRoutingFirewallRule** : create an IPv4 routing firewall rule +- **updateRoutingFirewallRule** : update an IPv4 routing firewall rule +- **deleteRoutingFirewallRule** : delete an IPv4 routing firewall rule +- **listRoutingFirewallRules** : list IPv4 routing firewall rules + + +Manage AS number for Dynamic Routing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create network with dynamic routing, operators must add AS number ranges in advance by navigating to Infrastructure -> Zones -> choose a zone -> AS Number. + +|dynamic-routing-as-number-ranges.png| + +Supported CloudStack APIs for operators to manage the AS number ranges and AS numbers are: + +- **createASNRange** : Creates a range of Autonomous Systems for BGP Dynamic Routing +- **listASNRanges** : List Autonomous Systems Number Ranges +- **deleteASNRange** : deletes a range of Autonomous Systems for BGP Dynamic Routing +- **listASNumbers** : List Autonomous Systems Numbers +- **releaseASNumber** : Releases an AS Number back to the pool + +Operators can list the AS numbers by navigating to Network -> AS Numbers + +|dynamic-routing-as-numbers.png| + + +Manage BPG peers for Dynamic Routing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create network with dynamic routing, operators must add BGP peers in advance. Guest networks with Dynamic Routing will connect to all BGP peers the account can access. + +|dynamic-routing-bgp-peers.png| + +Supported CloudStack APIs for operators to manage the BGP peers are: + +- **createBgpPeer** : create a BGP peer +- **dedicateBgpPeer** : dedicate a BGP peer to a domain or an account +- **deleteBgpPeer** : delete a BGP peer +- **listBgpPeers** : list BGP peers +- **releaseBgpPeer** : release a dedicated BGP peer from a domain or an account +- **updateBgpPeer** : update a BGP peer + + +Create Network with Dynamic Routing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The steps to create a network with dynamic routing is almost same as the network with static routing. The only difference is that, users need to choose a network offering with routing mode is Dynamic. + +During the network creation, CloudStack will + +- Allocate an AS number to the network +- If the network owner does not have dedicated BGP peers, or account setting "use.system.bgp.peers" is set to true, configure BGP sessions in the network VR to connect to all BGP peers the network owner can access. +- If the network owner has dedicated BGP peers, and account setting "use.system.bgp.peers" is set to false, configure BGP sessions in the network VR to connect to all dedicated BGP peers of the domain and the network owner. + +ROOT admin can change BGP peers of an existing network with Dynamic routing. After that, the network VR will only connect to selected BGP peers. + +|dynamic-routing-change-network-bgp-peers.png| + + +Create VPC with Dynamic Routing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The creation of VPC with Dynamic routing is almost as VPC with static routing. CloudStack will allocate an AS number to the VPC, and +- If the VPC owner does not have dedicated BGP peers, or account setting "use.system.bgp.peers" is set to true, configure BGP sessions in the VPC VR to connect to all BGP peers the VPC owner can access. +- If the VPC owner has dedicated BGP peers, and account setting "use.system.bgp.peers" is set to false, configure BGP sessions in the VPC VR to connect to all dedicated BGP peers of the domain and the VPC owner. + +ROOT admin can change BGP peers of an existing VPC with Dynamic routing. After that, the VPC VR will only connect to selected BGP peers. + +|dynamic-routing-change-vpc-bgp-peers.png| + +.. note:: + If a BGP peer is added, removed or updated, the existing network VRs and VPC VRs will not be automatically reconfigured. Please restart the network or VPC to reconfigure the VRs. + + +CloudStack Kubernetes Service support on ROUTED networks and VPCs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To support CloudStack Kubernetes Service on ROUTED networks and VPCs, operators have to configure the networks. + +- The management server must be able to connect to the VMs on ROUTED networks or VPCs +- Some routing firewall Ingress rules (for ROUTED networks) or Network ACL Ingress rules (for ROUTED VPCs) must be configured to open the following ports. + +.. cssclass:: table-striped table-bordered table-hover + +================= ======================== +Ports Description +================= ======================== +22 The management server configures the CKS nodes via port 22. +6443 The port of Kubernetes API server. +8080 The port of Kubernetes Dashboard. +================= ======================== + +For more information, see `“CloudStack Kubernetes Service” <../plugins/cloudstack-kubernetes-service.html>`_. + + +.. |manage-ipv4-subnets-for-zone.png| image:: /_static/images/manage-ipv4-subnets-for-zone.png + :alt: Manage IPv4 subnets for zone + +.. |manage-ipv4-subnets-for-networks.png| image:: /_static/images/manage-ipv4-subnets-for-networks.png + :alt: Manage IPv4 subnets for guest networks + +.. |routed-add-network-offering.png| image:: /_static/images/routed-add-network-offering.png + :alt: Add network offering with ROUTED mode + +.. |routed-add-vpc-offering.png| image:: /_static/images/routed-add-vpc-offering.png + :alt: Add vpc offering with ROUTED mode + +.. |routed-add-network-cidrsize.png| image:: /_static/images/routed-add-network-cidrsize.png + :alt: Add ROUTED network with specified cidr size + +.. |routed-ipv4-routes.png| image:: /_static/images/routed-ipv4-routes.png + :alt: IPv4 static routes + +.. |routed-ipv4-routing-firewall.png| image:: /_static/images/routed-ipv4-routing-firewall.png + :alt: IPv4 routing firewall rules + +.. |dynamic-routing-as-number-ranges.png| image:: /_static/images/dynamic-routing-as-number-ranges.png + :alt: AS number ranges for Dynamic Routing + +.. |dynamic-routing-as-numbers.png| image:: /_static/images/dynamic-routing-as-numbers.png + :alt: AS numbers for Dynamic Routing + +.. |dynamic-routing-bgp-peers.png| image:: /_static/images/dynamic-routing-bgp-peers.png + :alt: BGP peers for Dynamic Routing + +.. |dynamic-routing-change-network-bgp-peers.png| image:: /_static/images/dynamic-routing-change-network-bgp-peers.png + :alt: Change BGP peers for network with Dynamic Routing + +.. |dynamic-routing-change-vpc-bgp-peers.png| image:: /_static/images/dynamic-routing-change-vpc-bgp-peers.png + :alt: Change BGP peers for VPC with Dynamic Routing + diff --git a/source/adminguide/networking/elastic_ips.rst b/source/adminguide/networking/elastic_ips.rst index fe83a3bf7c..2eb02a0a73 100644 --- a/source/adminguide/networking/elastic_ips.rst +++ b/source/adminguide/networking/elastic_ips.rst @@ -20,11 +20,11 @@ About Elastic IPs Elastic IP (EIP) addresses are the IP addresses that are associated with an account, and act as static IP addresses. The account owner has the complete control over the Elastic IP addresses that belong to the -account. As an account owner, you can allocate an Elastic IP to a VM of +account. As an account owner, you can allocate an Elastic IP to an instance of your choice from the EIP pool of your account. Later if required you can -reassign the IP address to a different VM. This feature is extremely -helpful during VM failure. Instead of replacing the VM which is down, -the IP address can be reassigned to a new VM in your account. +reassign the IP address to a different instance. This feature is extremely +helpful during instance failure. Instead of replacing the instance which is down, +the IP address can be reassigned to a new instance in your account. Similar to the public IP address, Elastic IP addresses are mapped to their associated private IP addresses by using StaticNAT. The EIP @@ -47,11 +47,11 @@ through the firewall. The EIP work flow is as follows: -- When a user VM is deployed, a public IP is automatically acquired +- When a user instance is deployed, a public IP is automatically acquired from the pool of public IPs configured in the zone. This IP is owned - by the VM's account. + by the instance's account. -- Each VM will have its own private IP. When the user VM starts, Static +- Each instance will have its own private IP. When the user instance starts, Static NAT is provisioned on the NetScaler device by using the Inbound Network Address Translation (INAT) and Reverse NAT (RNAT) rules between the public IP and the private IP. @@ -59,21 +59,21 @@ The EIP work flow is as follows: .. note:: Inbound NAT (INAT) is a type of NAT supported by NetScaler, in which the destination IP address is replaced in the packets from the public - network, such as the Internet, with the private IP address of a VM in + network, such as the Internet, with the private IP address of an instance in the private network. Reverse NAT (RNAT) is a type of NAT supported by NetScaler, in which the source IP address is replaced in the packets - generated by a VM in the private network with the public IP address. + generated by an instance in the private network with the public IP address. - This default public IP will be released in two cases: - - When the VM is stopped. When the VM starts, it again receives a + - When the instance is stopped. When the instance starts, it again receives a new public IP, not necessarily the same one allocated initially, from the pool of Public IPs. - The user acquires a public IP (Elastic IP). This public IP is associated with the account, but will not be mapped to any private IP. However, the user can enable Static NAT to associate this IP - to the private IP of a VM in the account. The Static NAT rule for + to the private IP of an instance in the account. The Static NAT rule for the public IP can be disabled at any time. When Static NAT is disabled, a new public IP is allocated from the pool, which is not necessarily be the same one allocated initially. @@ -83,21 +83,21 @@ flexibility to choose not to allocate a public IP by default. You can use the Associate Public IP option to turn on or off the automatic public IP assignment in the EIP-enabled Basic zones. If you turn off the automatic public IP assignment while creating a network offering, only a -private IP is assigned to a VM when the VM is deployed with that network -offering. Later, the user can acquire an IP for the VM and enable static +private IP is assigned to an instance when the instance is deployed with that network +offering. Later, the user can acquire an IP for the instance and enable static NAT. For more information on the Associate Public IP option, see `"Creating a New Network Offering" `_. .. note:: - The Associate Public IP feature is designed only for use with user VMs. + The Associate Public IP feature is designed only for use with user instances. The System VMs continue to get both public IP and private by default, irrespective of the network offering configuration. New deployments which use the default shared network offering with EIP and ELB services to create a shared network in the Basic zone will -continue allocating public IPs to each user VM. +continue allocating public IPs to each user instance. .. |eip-ns-basiczone.png| image:: /_static/images/eip-ns-basiczone.png diff --git a/source/adminguide/networking/external_firewalls_and_load_balancers.rst b/source/adminguide/networking/external_firewalls_and_load_balancers.rst index 91f5898d74..a753886c6c 100644 --- a/source/adminguide/networking/external_firewalls_and_load_balancers.rst +++ b/source/adminguide/networking/external_firewalls_and_load_balancers.rst @@ -17,16 +17,15 @@ External Firewalls and Load Balancers ------------------------------------- -CloudStack is capable of replacing its Virtual Router with an external -Juniper SRX device and an optional external NetScaler or F5 load -balancer for gateway and load balancing services. In this case, the VMs -use the SRX as their gateway. +CloudStack is capable of moving some of its Virtual Router networking functionality +to some of the external network service providers such as e.g. NetScaler. + About Using a NetScaler Load Balancer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Citrix NetScaler is supported as an external network element for load +Citrix NetScaler is supported as an external Network element for load balancing in zones that use isolated networking in advanced zones. Set up an external load balancer when you want to provide load balancing through means other than CloudStack's provided virtual router. @@ -36,21 +35,21 @@ through means other than CloudStack's provided virtual router. Elastic IP or Elastic LB services are enabled. When NetScaler load balancer is used to provide EIP or ELB services in a -Basic zone, ensure that all guest VM traffic must enter and exit through +Basic zone, ensure that all Guest Instance traffic must enter and exit through the NetScaler device. When inbound traffic goes through the NetScaler device, traffic is routed by using the NAT protocol depending on the EIP/ELB configured on the public IP to the private IP. The traffic that -is originated from the guest VMs usually goes through the layer 3 +is originated from the Guest Instances usually goes through the layer 3 router. To ensure that outbound traffic goes through NetScaler device providing EIP/ELB, layer 3 router must have a policy-based routing. A policy-based route must be set up so that all traffic originated from -the guest VM's are directed to NetScaler device. This is required to -ensure that the outbound traffic from the guest VM's is routed to a +the Guest Instance's are directed to NetScaler device. This is required to +ensure that the outbound traffic from the Guest Instance's is routed to a public IP by using NAT.For more information on Elastic IP, see `"About Elastic IP" <#about-elastic-ip>`_. The NetScaler can be set up in direct (outside the firewall) mode. It -must be added before any load balancing rules are deployed on guest VMs +must be added before any load balancing rules are deployed on Guest Instances in the zone. The functional behavior of the NetScaler with CloudStack is the same as @@ -76,7 +75,7 @@ summarizes how these variants are treated in CloudStack. **VPX** -- Virtual appliance. Can run as VM on XenServer, ESXi, and Hyper-V +- Virtual appliance. Can run as instance on XenServer, ESXi, and Hyper-V hypervisors. Same functionality as MPX - Supported on ESXi and XenServer. Same functional support as for MPX. @@ -98,12 +97,12 @@ Configuring SNMP Community String on a RHEL Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The SNMP Community string is similar to a user id or password that -provides access to a network device, such as router. This string is sent +provides access to a Network device, such as router. This string is sent along with all SNMP requests. If the community string is correct, the device responds with the requested information. If the community string is incorrect, the device discards the request and does not respond. -The NetScaler device uses SNMP to communicate with the VMs. You must +The NetScaler device uses SNMP to communicate with the instances. You must install SNMP and configure SNMP Community string for a secure communication between the NetScaler device and the RHEL machine. @@ -180,8 +179,8 @@ communication between the NetScaler device and the RHEL machine. Initial Setup of External Firewalls and Load Balancers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When the first VM is created for a new account, CloudStack programs the -external firewall and load balancer to work with the VM. The following +When the first instance is created for a new account, CloudStack programs the +external firewall and load balancer to work with the instance. The following objects are created on the firewall: - A new logical interface to connect to the account's private VLAN. The @@ -209,14 +208,14 @@ Ongoing Configuration of External Firewalls and Load Balancers Additional user actions (e.g. setting a port forward) will cause further programming of the firewall and load balancer. A user may request additional public IP addresses and forward traffic received at these IPs -to specific VMs. This is accomplished by enabling static NAT for a -public IP address, assigning the IP to a VM, and specifying a set of +to specific instances. This is accomplished by enabling static NAT for a +public IP address, assigning the IP to an instance, and specifying a set of protocols and port ranges to open. When a static NAT rule is created, CloudStack programs the zone's external firewall with the following objects: - A static NAT rule that maps the public IP address to the private IP - address of a VM. + address of an instance. - A security policy that allows traffic within the set of protocols and port ranges that are specified. @@ -234,14 +233,14 @@ Load Balancer Rules ~~~~~~~~~~~~~~~~~~~ A CloudStack user or administrator may create load balancing rules that -balance traffic received at a public IP to one or more VMs. A user +balance traffic received at a public IP to one or more instances. A user creates a rule, specifies an algorithm, and assigns the rule to a set of -VMs. +instances. .. note:: - If you create load balancing rules while using a network service + If you create load balancing rules while using a Network service offering that includes an external load balancer device such as - NetScaler, and later change the network service offering to one that + NetScaler, and later change the Network service offering to one that uses the CloudStack virtual router, you must create a firewall rule on the virtual router for each of your existing load balancing rules so that they continue to function. @@ -256,7 +255,7 @@ Adding a Load Balancer Rule #. In the left navigation, choose Network. -#. Click the name of the network where you want to load balance the +#. Click the name of the Network where you want to load balance the traffic. #. Click Public IP Addresses. @@ -270,7 +269,7 @@ Adding a Load Balancer Rule IP when you create the load balancing rule, which is listed in the IP Addresses page when the rule is created. - To do that, select the name of the network, then click Add Load + To do that, select the name of the Network, then click Add Load Balancer tab. Continue with #7. #. Fill in the following: @@ -280,7 +279,7 @@ Adding a Load Balancer Rule - **Public Port**: The port receiving incoming traffic to be balanced. - - **Private Port**: The port that the VMs will use to receive the + - **Private Port**: The port that the instances will use to receive the traffic. - **Algorithm**: Choose the load balancing algorithm you want @@ -292,6 +291,11 @@ Adding a Load Balancer Rule algorithm for the stickiness policy. See Sticky Session Policies for Load Balancer Rules. + - **Protocol**: The protocol for the Load Balancer Rule such as tcp, udp, tcp-proxy or ssl. + + - **SSL Certificate**: The SSL certificate assigned to the Load Balancer Rule. + This is visible only when protocol is ssl. See :ref:`conf-ssl-cert`. + - **AutoScale**: Click Configure and complete the AutoScale configuration as explained in :ref:`conf-autoscale`. @@ -318,7 +322,7 @@ Adding a Load Balancer Rule health check failures that are required before declaring an instance unhealthy. Default: 10. -#. Click Add VMs, then select two or more VMs that will divide the load +#. Click Add instances, then select two or more instances that will divide the load of incoming traffic, and click Apply. The new load balancer rule appears in the list. You can repeat these @@ -348,9 +352,87 @@ automatically generated. A variety of options are provided to control the exact behavior of cookies, such as how they are generated and whether they are cached. -For the most up to date list of available stickiness methods, see the -CloudStack UI or call listNetworks and check the -SupportedStickinessMethods capability. +There are three stickiness methods that are supported explained with the possible options to configure as below, + +1. Lbcookie: In this method, cookie is created by the load balancer and sent to the client. +The client sends this cookie back with every subsequent request, and the load balancer uses the +cookie information to determine which backend server to route the request to. + +Following are the options available to configure, + +- Cookie name: This is the name of the cookie that the load balancer will create and send to the client. + +- Mode: This option determines how the load balancer should handle the cookie (default value is insert). + The available options are: + + a. Insert: The load balancer will insert the cookie into the client's request. + b. Rewrite: The load balancer will rewrite the cookie in the client's request if it already exists. + c. Prefix: The load balancer will prefix the cookie name with a specified prefix. + d. Indirect: The load balancer will insert an indirect cookie, which contains a reference to the actual cookie value. + +- No cache: This option specifies whether the cookie should be cached by the client's browser. + If this option is enabled, the client's browser will not cache the cookie. + +- Indirect: If this is provided, then the cookie value will contain a reference to the actual value, which will be stored on the load balancer. + +- Post only: This option specifies whether the cookie should be sent only with POST requests. + +- Domain: This option specifies the domain for which the cookie is valid. You can specify a domain name or IP address. + +2. Appcookie: In this method, the application running on the backend servers creates a cookie and +sends it to the client. The client sends this cookie back with every subsequent request, and the +load balancer uses the cookie information to determine which backend server to route the request to. + +Following are the options available to configure, + +- Cookie name and mode are same as above + +- Length: This option specifies the length of the cookie value (default value is 52). + +- Hold time: This option specifies the length of time that the cookie should be held (default value is 3hours). + The cookie will be held for this amount of time, after which it will expire. + +- Request learn: This option specifies whether the load balancer should learn the cookie value from the first request that it receives. + +- Prefix: This option specifies a prefix to be added to the cookie value. + +3. Source-based: In this method, the load balancer uses the source IP address of the client +to determine which backend server to route the request to. The load balancer maintains a mapping of +client IP addresses to backend servers and uses this mapping to ensure that subsequent requests from +the same client are always routed to the same backend server. + +- Table size: This option specifies the maximum number of entries (default 200k) that can be stored in the source-based stickiness table. + The table stores mappings between client IP addresses and backend servers. + +- Expires: This option specifies the length of time (default 30m) that a mapping between a client IP address and a backend server + should be kept in the stickiness table. After this time has elapsed, the mapping will expire and be removed from the table. + +4. None: If None is selected after a sticky policy is already configured then it will be removed. + +Load Balancer Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(CloudStack Virtual Router and Vpc Virtual Router only) + +CloudStack Virtual Routers use haproxy to provide load balancer.The following is the configurations of haproxy. + +.. cssclass:: table-striped table-bordered table-hover + +================= ================ ==================================================================================================== +Configuration Scope Description +================= ================ ==================================================================================================== +maxconn global the maximum per-process number of concurrent connections. The default value is 4096. +maxpipes global the maximum per-process number of pipes. The default value is maxconn/4. +timeout connect defaults the maximum time to wait for a connection attempt to a server to succeed. The default value is 5 seconds. +timeout client defaults the maximum inactivity time on the server side. The default value is 50 seconds. +timeout server defaults the maximum inactivity time on the client side. The default value is 50 seconds. +option defaults the following options are enabled: redispatch, forwardfor, httpclose +stats enable stats Enable statistics reporting with default settings. It listens on :8081. The port can be changed by global setting "network.loadbalancer.haproxy.stats.port". +stats uri stats Enable statistics and define the URI prefix to access them. The default value is "/admin?stats". The URI can be changed by global setting "network.loadbalancer.haproxy.stats.uri". +stats realm stats Enable statistics and set authentication realm. The default value is "Haproxy\\ Statistics". +stats auth stats Enable statistics with authentication and grant access to an account. The default value is "admin1:AdMiN123". The username/password can be changed by global setting "network.loadbalancer.haproxy.stats.auth". +================= ================ ==================================================================================================== + .. _health-check: @@ -378,7 +460,7 @@ the resource later becomes available again, the periodic health check will discover it, and the resource will once again be added to the pool of resources that can receive requests from the load balancer. At any given time, the most recent result of the health check is displayed in -the UI. For any VM that is attached to a load balancer rule with a +the UI. For any instance that is attached to a load balancer rule with a health check configured, the state will be shown as UP or DOWN in the UI depending on the result of the most recent health check. @@ -393,26 +475,90 @@ For details on how to set a health check policy using the UI, see :ref:`adding-lb-rule`. +.. _conf-ssl-cert: + +Configuring SSL Certificate for Load Balancer Rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSL Offloading allows load balancers to handle encryption and decryption of +HTTP(s) traffic giving plain text HTTP to the back end servers freeing them +from the resource intensive task of handling encryption and decryption. +SSL Offloading supports CloudStack Virtual Router since Apache CloudStack 4.22.0. + +- Upload SSL certificates + +SSL certificate is required for SSL offloading feature. As the first step, users +need to upload SSL certificates for the accounts or projects. + +|ssl-certificate-account.png| + +Click "Upload SSL Certificate" button, input the following fields in the dialog, click "Submit" + + * Name: the name of the SSL certificate. This is required. + * Certificate: the SSL certificate. This is required. + * Private Key: the private key of the SSL certificate. This is required. + * Certificate chain: the ROOT CA and intermediate certificate(s) of the SSL certificate. Please input if exist, otherwise the SSL certificate might not work. + * Password: the password of the private key. Currently it is unsupported when use CloudStack Virtual Router for SSL offloading. + * Revocation check: Whether enables revocation checking for certificates. Please do not check if self-signed SSL certificate. + +|ssl-certificate-upload.png| + +Users can view or remove the SSL certificates on the same page. + +|ssl-certificate-list.png| + +For projects, go to the project page and click "Certificates" tab + +|ssl-certificate-project.png| + +- Create Load balancer rule with SSL Certificate + +SSL certificate can be configured only when the protocol of load balancer rule is ssl. + +|ssl-certificate-new-lb-rule.png| + +Click "SSL certificate" button, select a SSL certificate, click "OK" + +|ssl-certificate-new-lb-rule-select.png| + +- Assign SSL certificate to existing Load balancer rule + +If the load balancer rule has been created without SSL certificate, update protocol to SSL if it is not + +|ssl-certificate-update-lb-rule-protocol.png| + +Click "Manage" button under the "SSL certificate" field, select a SSL certificate, +click "Replace" or "Assign" button to assign a new SSL certificate. + +|ssl-certificate-update-lb-rule-ssl-cert.png| + +User can remove the SSL certificate from load balancer rule by clicking "Remove" button. + +.. note:: + Since SSL offloading increases CPU utilization on the load balancer, + please allocate more resources to the Virtual Router when expecting high traffic. + + .. _conf-autoscale: Configuring AutoScale ~~~~~~~~~~~~~~~~~~~~~ AutoScaling allows you to scale your back-end services or application -VMs up or down seamlessly and automatically according to the conditions +instances up or down seamlessly and automatically according to the conditions you define. With AutoScaling enabled, you can ensure that the number of -VMs you are using seamlessly scale up when demand increases, and +instances you are using seamlessly scale up when demand increases, and automatically decreases when demand subsides. Thus it helps you save -compute costs by terminating underused VMs automatically and launching -new VMs when you need them, without the need for manual intervention. +compute costs by terminating underused instances automatically and launching +new instances when you need them, without the need for manual intervention. -NetScaler AutoScaling is designed to seamlessly launch or terminate VMs +NetScaler AutoScaling is designed to seamlessly launch or terminate instances based on user-defined conditions. Conditions for triggering a scaleup or scaledown action can vary from a simple use case like monitoring the CPU usage of a server to a complex use case of monitoring a combination of server's responsiveness and its CPU usage. For example, you can -configure AutoScaling to launch an additional VM whenever CPU usage -exceeds 80 percent for 15 minutes, or to remove a VM whenever CPU usage +configure AutoScaling to launch an additional instance whenever CPU usage +exceeds 80 percent for 15 minutes, or to remove an instance whenever CPU usage is less than 20 percent for 30 minutes. CloudStack uses the NetScaler load balancer to monitor all aspects of a @@ -429,12 +575,12 @@ Prerequisites Before you configure an AutoScale rule, consider the following: - Ensure that the necessary template is prepared before configuring - AutoScale. When a VM is deployed by using a template and when it + AutoScale. When an instance is deployed by using a template and when it comes up, the application should be up and running. .. note:: If the application is not running, the NetScaler device considers the - VM as ineffective and continues provisioning the VMs unconditionally + instance as ineffective and continues provisioning the instances unconditionally until the resource limit is exhausted. - Deploy the templates you prepared. Ensure that the applications come @@ -445,14 +591,14 @@ Before you configure an AutoScale rule, consider the following: - The AutoScale feature supports the SNMP counters that can be used to define conditions for taking scale up or scale down actions. To monitor the SNMP-based counter, ensure that the SNMP agent is - installed in the template used for creating the AutoScale VMs, and + installed in the template used for creating the AutoScale instances, and the SNMP operations work with the configured SNMP community and port by using standard SNMP managers. For example, see `"Configuring SNMP Community String on a RHELServer" <#configuring-snmp-community-string-on-a-rhel-server>`_ to configure SNMP on a RHEL machine. -- Ensure that the endpointe.url parameter present in the Global +- Ensure that the endpoint.url parameter present in the Global Settings is set to the Management Server API URL. For example, ``http://10.102.102.22:8080/client/api``. In a multi-node Management Server deployment, use the virtual IP address configured in the load @@ -460,7 +606,7 @@ Before you configure an AutoScale rule, consider the following: that the NetScaler device has access to this IP address to provide AutoScale support. - If you update the endpointe.url, disable the AutoScale functionality + If you update the endpoint.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see :ref:`update-autoscale`. @@ -469,9 +615,9 @@ Before you configure an AutoScale rule, consider the following: the user participates in are disabled and then enabled to reflect the configuration changes in the NetScaler. -- In an advanced Zone, ensure that at least one VM should be present - before configuring a load balancer rule with AutoScale. Having one VM - in the network ensures that the network is in implemented state for +- In an advanced Zone, ensure that at least one instance should be present + before configuring a load balancer rule with AutoScale. Having one instance + in the Network ensures that the Network is in implemented state for configuring AutoScale. @@ -484,52 +630,52 @@ Specify the following: - **Template**: A template consists of a base OS image and application. A template is used to provision the new instance of an application on - a scaleup action. When a VM is deployed from a template, the VM can + a scaleup action. When an instance is deployed from a template, the instance can start taking the traffic from the load balancer without any admin - intervention. For example, if the VM is deployed for a Web service, + intervention. For example, if the instance is deployed for a Web service, it should have the Web server running, the database connected, and so on. - **Compute offering**: A predefined set of virtual hardware attributes, including CPU speed, number of CPUs, and RAM size, that - the user can select when creating a new virtual machine instance. - Choose one of the compute offerings to be used while provisioning a - VM instance as part of scaleup action. + the user can select when creating a new Instance. + Choose one of the compute offerings to be used while provisioning an + Instance as part of scaleup action. -- **Min Instance**: The minimum number of active VM instances that is - assigned to a load balancing rule. The active VM instances are the +- **Min Instance**: The minimum number of active instances that is + assigned to a load balancing rule. The active instances are the application instances that are up and serving the traffic, and are being load balanced. This parameter ensures that a load balancing - rule has at least the configured number of active VM instances are + rule has at least the configured number of active instances are available to serve the traffic. .. note:: - If an application, such as SAP, running on a VM instance is down for - some reason, the VM is then not counted as part of Min Instance + If an application, such as SAP, running on an instance is down for + some reason, the instance is then not counted as part of Min Instance parameter, and the AutoScale feature initiates a scaleup action if - the number of active VM instances is below the configured value. + the number of active instances is below the configured value. Similarly, when an application instance comes up from its earlier down state, this application instance is counted as part of the active instance count and the AutoScale process initiates a scaledown action when the active instance count breaches the Max instance value. -- **Max Instance**: Maximum number of active VM instances that **should +- **Max Instance**: Maximum number of active instances that **should be assigned to**\ a load balancing rule. This parameter defines the - upper limit of active VM instances that can be assigned to a load + upper limit of active instances that can be assigned to a load balancing rule. Specifying a large value for the maximum instance parameter might - result in provisioning large number of VM instances, which in turn - leads to a single load balancing rule exhausting the VM instances + result in provisioning large number of instances, which in turn + leads to a single load balancing rule exhausting the instances limit specified at the account or domain level. .. note:: - If an application, such as SAP, running on a VM instance is down for - some reason, the VM is not counted as part of Max Instance parameter. - So there may be scenarios where the number of VMs provisioned for a + If an application, such as SAP, running on an instance is down for + some reason, the instance is not counted as part of Max Instance parameter. + So there may be scenarios where the number of instances provisioned for a scaleup action might be more than the configured Max Instance value. - Once the application instances in the VMs are up from an earlier down + Once the application instances in the instances are up from an earlier down state, the AutoScale feature starts aligning to the configured Max Instance value. @@ -567,33 +713,33 @@ advanced settings, and specify the following: - **Quiet Time**: This is the cool down period after an AutoScale action is initiated. The time includes the time taken to complete - provisioning a VM instance from its template and the time taken by an + provisioning an instance from its template and the time taken by an application to be ready to serve traffic. This quiet time allows the fleet to come up to a stable state before any action can take place. The default is 300 seconds. -- **Destroy VM Grace Period**: The duration in seconds, after a - scaledown action is initiated, to wait before the VM is destroyed as +- **Destroy Instance Grace Period**: The duration in seconds, after a + scaledown action is initiated, to wait before the instance is destroyed as part of scaledown action. This is to ensure graceful close of any - pending sessions or transactions being served by the VM marked for + pending sessions or transactions being served by the instance marked for destroy. The default is 120 seconds. - **Security Groups**: Security groups provide a way to isolate traffic - to the VM instances. A security group is a group of VMs that filter + to the instances. A security group is a group of instances that filter their incoming and outgoing traffic according to a set of rules, - called ingress and egress rules. These rules filter network traffic + called ingress and egress rules. These rules filter Network traffic according to the IP address that is attempting to communicate with - the VM. + the instance. - **Disk Offerings**: A predefined set of disk size for primary data storage. - **SNMP Community**: The SNMP community string to be used by the NetScaler device to query the configured counter value from the - provisioned VM instances. Default is public. + provisioned instances. Default is public. - **SNMP Port**: The port number on which the SNMP agent that run on - the provisioned VMs is listening. Default port is 161. + the provisioned instances is listening. Default port is 161. - **User**: This is the user that the NetScaler device use to invoke scaleup and scaledown API calls to the cloud. If no option is @@ -606,7 +752,7 @@ advanced settings, and specify the following: Disabling and Enabling an AutoScale Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you want to perform any maintenance operation on the AutoScale VM +If you want to perform any maintenance operation on the AutoScale instances, disable the AutoScale configuration. When the AutoScale configuration is disabled, no scaleup or scaledown action is performed. You can use this downtime for the maintenance activities. To disable the @@ -637,20 +783,20 @@ again, then click the Enable AutoScale button. Runtime Considerations ^^^^^^^^^^^^^^^^^^^^^^ -- An administrator should not assign a VM to a load balancing rule +- An administrator should not assign an instance to a load balancing rule which is configured for AutoScale. -- Before a VM provisioning is completed if NetScaler is shutdown or - restarted, the provisioned VM cannot be a part of the load balancing +- Before an instance provisioning is completed if NetScaler is shutdown or + restarted, the provisioned instance cannot be a part of the load balancing rule though the intent was to assign it to a load balancing rule. To - workaround, rename the AutoScale provisioned VMs based on the rule - name or ID so at any point of time the VMs can be reconciled to its + workaround, rename the AutoScale provisioned instances based on the rule + name or ID so at any point of time the instances can be reconciled to its load balancing rule. - Making API calls outside the context of AutoScale, such as destroyVM, - on an autoscaled VM leaves the load balancing configuration in an - inconsistent state. Though VM is destroyed from the load balancer - rule, NetScaler continues to show the VM as a service assigned to a + on an autoscaled instance leaves the load balancing configuration in an + inconsistent state. Though instance is destroyed from the load balancer + rule, NetScaler continues to show the instance as a service assigned to a rule. @@ -658,3 +804,19 @@ Runtime Considerations :alt: Configuring AutoScale. .. |EnableDisable.png| image:: /_static/images/enable-disable-autoscale.png :alt: button to enable or disable AutoScale. +.. |ssl-certificate-account.png| image:: /_static/images/ssl-certificate-account.png + :alt: Manage certificates for account. +.. |ssl-certificate-upload.png| image:: /_static/images/ssl-certificate-upload.png + :alt: Upload SSL certificate for account. +.. |ssl-certificate-list.png| image:: /_static/images/ssl-certificate-list.png + :alt: List of certificates for account. +.. |ssl-certificate-project.png| image:: /_static/images/ssl-certificate-project.png + :alt: Manage certificates for project. +.. |ssl-certificate-new-lb-rule.png| image:: /_static/images/ssl-certificate-new-lb-rule.png + :alt: Create load balancer rule with SSL protocol +.. |ssl-certificate-new-lb-rule-select.png| image:: /_static/images/ssl-certificate-new-lb-rule-select.png + :alt: Select SSL certificate for new load balancer rule. +.. |ssl-certificate-update-lb-rule-protocol.png| image:: /_static/images/ssl-certificate-update-lb-rule-protocol.png + :alt: Update protocol of load balancer rule to SSL. +.. |ssl-certificate-update-lb-rule-ssl-cert.png| image:: /_static/images/ssl-certificate-update-lb-rule-ssl-cert.png + :alt: Manage certificates of load balancer rule. diff --git a/source/adminguide/networking/global_server_load_balancing.rst b/source/adminguide/networking/global_server_load_balancing.rst index fef3eb71df..a357564d34 100644 --- a/source/adminguide/networking/global_server_load_balancing.rst +++ b/source/adminguide/networking/global_server_load_balancing.rst @@ -75,7 +75,7 @@ A typical GSLB environment is comprised of the following components: services. - **GSLB Virtual Servers**: A GSLB virtual server refers to one or more - GSLB services and balances traffic between traffic across the VMs in + GSLB services and balances traffic between traffic across the instances in multiple zones by using the CloudStack functionality. It evaluates the configured GSLB methods or algorithms to select a GSLB service to which to send the client requests. One or more virtual servers from @@ -273,11 +273,11 @@ Prerequisites and Guidelines A zone shall be considered as GSLB capable only if a GSLB service provider is provisioned in the zone. -- When users have VMs deployed in multiple availability zones which are +- When users have instances deployed in multiple availability zones which are GSLB enabled, they can use the GSLB functionality to load balance - traffic across the VMs in multiple zones. + traffic across the instances in multiple zones. -- The users can use GSLB to load balance across the VMs across zones in +- The users can use GSLB to load balance across the instances across zones in a region only if the admin has enabled GSLB in that region. - The users can load balance traffic across the availability zones in diff --git a/source/adminguide/networking/guest_traffic.rst b/source/adminguide/networking/guest_traffic.rst index 51374d129b..1d5443b5fc 100644 --- a/source/adminguide/networking/guest_traffic.rst +++ b/source/adminguide/networking/guest_traffic.rst @@ -17,8 +17,8 @@ Guest Traffic ------------- -A network can carry guest traffic only between VMs within one zone. -Virtual machines in different zones cannot communicate with each other +A network can carry guest traffic only between Instances within one zone. +Instances in different zones cannot communicate with each other using their IP addresses; they must communicate with each other by routing through a public IP address. @@ -27,7 +27,7 @@ See a typical guest traffic setup given below: |guest-traffic-setup.png| Typically, the Management Server automatically creates a virtual router -for each network. A virtual router is a special virtual machine that +for each network. A virtual router is a special Instance that runs on the hosts. Each virtual router in an isolated network has three network interfaces. If multiple public VLAN is used, the router will have multiple public interfaces. Its eth0 interface serves as the @@ -38,12 +38,12 @@ If multiple public VLAN is used, the router will have multiple public interfaces. The virtual router provides DHCP and will automatically assign an IP -address for each guest VM within the IP range assigned for the network. -The user can manually reconfigure guest VMs to assume different IP +address for each Guest Instance within the IP range assigned for the network. +The user can manually reconfigure Guest Instances to assume different IP addresses. Source NAT is automatically configured in the virtual router to forward -outbound traffic for all guest VMs +outbound traffic for all Guest Instances .. |guest-traffic-setup.png| image:: /_static/images/guest-traffic-setup.png diff --git a/source/adminguide/networking/inter_vlan_routing.rst b/source/adminguide/networking/inter_vlan_routing.rst index fd651a8875..93f24e56df 100644 --- a/source/adminguide/networking/inter_vlan_routing.rst +++ b/source/adminguide/networking/inter_vlan_routing.rst @@ -22,12 +22,12 @@ traffic between VLANs. This feature enables you to build Virtual Private Clouds (VPC), an isolated segment of your cloud, that can hold multi-tier applications. These tiers are deployed on different VLANs that can communicate with each other. You provision VLANs to the tiers -your create, and VMs can be deployed on different tiers. The VLANs are +your create, and instances can be deployed on different tiers. The VLANs are connected to a virtual router, which facilitates communication between -the VMs. In effect, you can segment VMs by means of VLANs into different +the instances. In effect, you can segment instances by means of VLANs into different networks that can host multi-tier applications, such as Web, Application, or Database. Such segmentation by means of VLANs logically -separate application VMs for higher security and lower broadcasts, while +separate application instances for higher security and lower broadcasts, while remaining physically connected to the same device. This feature is supported on XenServer, KVM, and VMware hypervisors. @@ -35,23 +35,23 @@ This feature is supported on XenServer, KVM, and VMware hypervisors. The major advantages are: - The administrator can deploy a set of VLANs and allow users to deploy - VMs on these VLANs. A guest VLAN is randomly alloted to an account - from a pre-specified set of guest VLANs. All the VMs of a certain + instances on these VLANs. A guest VLAN is randomly allotted to an account + from a pre-specified set of guest VLANs. All the instances of a certain tier of an account reside on the guest VLAN allotted to that account. .. note:: A VLAN allocated for an account cannot be shared between multiple accounts. - The administrator can allow users create their own VPC and deploy the - application. In this scenario, the VMs that belong to the account are + application. In this scenario, the instances that belong to the account are deployed on the VLANs allotted to that account. - Both administrators and users can create multiple VPCs. The guest - network NIC is plugged to the VPC virtual router when the first VM is + network NIC is plugged to the VPC virtual router when the first instance is deployed in a tier. - The administrator can create the following gateways to send to or - receive traffic from the VMs: + receive traffic from the instances: - **VPN Gateway**: For more information, see `"Creating a VPN gateway for the VPC" <#creating-a-vpn-gateway-for-the-vpc>`_. @@ -70,12 +70,12 @@ The major advantages are: For example: - **VLANs and Public Gateway**: For example, an application is - deployed in the cloud, and the Web application VMs communicate + deployed in the cloud, and the Web application instances communicate with the Internet. - **VLANs, VPN Gateway, and Public Gateway**: For example, an - application is deployed in the cloud; the Web application VMs - communicate with the Internet; and the database VMs communicate + application is deployed in the cloud; the Web application instances + communicate with the Internet; and the database instances communicate with the on-premise devices. - The administrator can define Network Access Control List (ACL) on the diff --git a/source/adminguide/networking/ip_forwarding_and_firewalling.rst b/source/adminguide/networking/ip_forwarding_and_firewalling.rst index e13fe63278..a0a43adfb6 100644 --- a/source/adminguide/networking/ip_forwarding_and_firewalling.rst +++ b/source/adminguide/networking/ip_forwarding_and_firewalling.rst @@ -26,9 +26,9 @@ To allow incoming traffic, users may set up firewall rules and/or port forwarding rules. For example, you can use a firewall rule to open a range of ports on the public IP address, such as 33 through 44. Then use port forwarding rules to direct traffic from individual ports within -that range to specific ports on user VMs. For example, one port +that range to specific ports on user instances. For example, one port forwarding rule could route incoming traffic on the public IP's port 33 -to port 100 on one user VM's private IP. +to port 100 on one user instance's private IP. Firewall Rules @@ -108,9 +108,6 @@ Prerequisites and Guidelines Consider the following scenarios to apply egress firewall rules: -- Egress firewall rules are supported on Juniper SRX and virtual - router. - - The egress firewall rules are not supported on shared networks. - Allow the egress traffic from specified source CIDR. The Source CIDR @@ -138,7 +135,7 @@ Configuring an Egress Firewall Rule #. To add an egress rule, click the Egress rules tab and fill out the following fields to specify what type of traffic is allowed to be - sent out of VM instances in this guest network: + sent out of instances in this guest network: |egress-firewall-rule.png| @@ -148,7 +145,7 @@ Configuring an Egress Firewall Rule the destination. For example, 192.168.0.0/22. To allow all CIDRs, set to 0.0.0.0/0. - - **Protocol**: The networking protocol that VMs uses to send + - **Protocol**: The networking protocol that instances uses to send outgoing traffic. The TCP and UDP protocols are typically used for data exchange and end-user communications. The ICMP protocol is typically used to send error messages or network monitoring data. @@ -195,7 +192,7 @@ traffic. While implementing a guest network, CloudStack adds the firewall egress rule specific to the default egress policy for the guest network. -This feature is supported only on virtual router and Juniper SRX. +This feature is supported only on the virtual router. #. Create a network offering with your desirable default egress policy: @@ -224,15 +221,15 @@ Port Forwarding ~~~~~~~~~~~~~~~ A port forward service is a set of port forwarding rules that define a -policy. A port forward service is then applied to one or more guest VMs. -The guest VM then has its inbound network access managed according to +policy. A port forward service is then applied to one or more Guest Instances. +The Guest Instance then has its inbound network access managed according to the policy defined by the port forwarding service. You can optionally specify one or more CIDRs to filter the source IPs. This is useful when you want to allow only incoming requests from certain IP addresses to be forwarded. -A guest VM can be in any number of port forward services. Port forward -services can be defined but have no members. If a guest VM is part of +A Guest Instance can be in any number of port forward services. Port forward +services can be defined but have no members. If a Guest Instance is part of more than one network, port forwarding rules will function only if they are defined on the default network @@ -248,11 +245,11 @@ To set up port forwarding: zone in CloudStack. See Adding a Zone and Pod in the Installation Guide. -#. Add one or more VM instances to CloudStack. +#. Add one or more instances to CloudStack. #. In the left navigation bar, click Network. -#. Click the name of the guest network where the VMs are running. +#. Click the name of the guest network where the instances are running. #. Choose an existing IP address or acquire a new IP address. See `"Acquiring a New IP Address" <#acquiring-a-new-ip-address>`_. diff --git a/source/adminguide/networking/ip_reservation_in_guest_networks.rst b/source/adminguide/networking/ip_reservation_in_guest_networks.rst index 028f504b17..87bb13466d 100644 --- a/source/adminguide/networking/ip_reservation_in_guest_networks.rst +++ b/source/adminguide/networking/ip_reservation_in_guest_networks.rst @@ -18,24 +18,24 @@ IP Reservation in Isolated Guest Networks ----------------------------------------- In isolated guest networks, a part of the guest IP address space can be -reserved for non-CloudStack VMs or physical servers. To do so, you +reserved for non-CloudStack instances or physical servers. To do so, you configure a range of Reserved IP addresses by specifying the CIDR when a guest network is in Implemented state. If your customers wish to have -non-CloudStack controlled VMs or physical servers on the same network, +non-CloudStack controlled instances or physical servers on the same network, they can share a part of the IP address space that is primarily provided to the guest network. In an Advanced zone, an IP address range or a CIDR is assigned to a network when the network is defined. The CloudStack virtual router acts as the DHCP server and uses CIDR for assigning IP addresses to the guest -VMs. If you decide to reserve CIDR for non-CloudStack purposes, you can +instances. If you decide to reserve CIDR for non-CloudStack purposes, you can specify a part of the IP address range or the CIDR that should only be -allocated by the DHCP service of the virtual router to the guest VMs +allocated by the DHCP service of the virtual router to the Guest Instances created in CloudStack. The remaining IPs in that network are called Reserved IP Range. When IP reservation is configured, the administrator -can add additional VMs or physical servers that are not part of +can add additional instances or physical servers that are not part of CloudStack to the same network and assign them the Reserved IP -addresses. CloudStack guest VMs cannot acquire IPs from the Reserved IP +addresses. CloudStack Guest Instances cannot acquire IPs from the Reserved IP Range. @@ -52,13 +52,13 @@ machines: - No IP Reservation is done by default. -- Guest VM CIDR you specify must be a subset of the network CIDR. +- Guest instance CIDR you specify must be a subset of the network CIDR. -- Specify a valid Guest VM CIDR. IP Reservation is applied only if no - active IPs exist outside the Guest VM CIDR. +- Specify a valid Guest instance CIDR. IP Reservation is applied only if no + active IPs exist outside the Guest instance CIDR. - You cannot apply IP Reservation if any VM is alloted with an IP - address that is outside the Guest VM CIDR. + You cannot apply IP Reservation if any instance is allotted with an IP + address that is outside the Guest instance CIDR. - To reset an existing IP Reservation, apply IP reservation by specifying the value of network CIDR in the CIDR field. @@ -68,29 +68,29 @@ machines: .. cssclass:: table-striped table-bordered table-hover - ===== ============= ============== ======================================== ======================================================== - Case CIDR Network CIDR Reserved IP Range for Non-CloudStack VMs Description - ===== ============= ============== ======================================== ======================================================== - 1 10.1.1.0/24 None None No IP Reservation. - 2 10.1.1.0/26 10.1.1.0/24 10.1.1.64 to 10.1.1.254 IP Reservation configured by the UpdateNetwork API with - guestvmcidr=10.1.1.0/26 or enter 10.1.1.0/26 in the CIDR - field in the UI. - 3 10.1.1.0/24 None None Removing IP Reservation by the UpdateNetwork API with - guestvmcidr=10.1.1.0/24 or enter 10.1.1.0/24 in the CIDR - field in the UI. - ===== ============= ============== ======================================== ======================================================== + ===== ============= ============== ============================================== ======================================================== + Case CIDR Network CIDR Reserved IP Range for Non-CloudStack instances Description + ===== ============= ============== ============================================== ======================================================== + 1 10.1.1.0/24 None None No IP Reservation. + 2 10.1.1.0/26 10.1.1.0/24 10.1.1.64 to 10.1.1.254 IP Reservation configured by the UpdateNetwork API with + guestvmcidr=10.1.1.0/26 or enter 10.1.1.0/26 in the CIDR + field in the UI. + 3 10.1.1.0/24 None None Removing IP Reservation by the UpdateNetwork API with + guestvmcidr=10.1.1.0/24 or enter 10.1.1.0/24 in the CIDR + field in the UI. + ===== ============= ============== ============================================== ======================================================== Limitations ~~~~~~~~~~~ - The IP Reservation is not supported if active IPs that are found - outside the Guest VM CIDR. + outside the Guest instance CIDR. - Upgrading network offering which causes a change in CIDR (such as upgrading an offering with no external devices to one with external devices) IP Reservation becomes void if any. Reconfigure IP - Reservation in the new re-implemeted network. + Reservation in the new re-implemented network. Best Practices @@ -98,7 +98,7 @@ Best Practices Apply IP Reservation to the guest network as soon as the network state changes to Implemented. If you apply reservation soon after the first -guest VM is deployed, lesser conflicts occurs while applying +Guest Instance is deployed, lesser conflicts occurs while applying reservation. @@ -113,7 +113,7 @@ Reserving an IP Range #. Click Edit. |ip-edit-icon.png| -#. In CIDR, specify the Guest VM CIDR. +#. In CIDR, specify the Guest instance CIDR. #. Click Apply. 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 46e438fd09..d1a0945aab 100644 --- a/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst +++ b/source/adminguide/networking/isolation_in_advanced_zone_with_vlan.rst @@ -20,7 +20,7 @@ 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' +The classic 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| diff --git a/source/adminguide/networking/manage_guest_networks.rst b/source/adminguide/networking/manage_guest_networks.rst new file mode 100644 index 0000000000..e0eefb936c --- /dev/null +++ b/source/adminguide/networking/manage_guest_networks.rst @@ -0,0 +1,44 @@ +.. 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. + + +Editing, Restarting, and Removing a Guest Network +-------------------------------------------------- + +.. note:: Ensure that all the Instances are removed before you remove a guest Network. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Network. + +#. In the Select view, select Guest Networks. + + All the guest Networks that you have created for the account are listed in the + page. + +#. Select the guest Network you want to work with. + +#. In the Details tab, click the "Delete Network" button + + You can also remove the guest Network by using the remove button in the Quick + View. + + You can edit the name, description, Network offering, CIDR, Network domain of a + guest Network. To do that, click the "Edit" button. + + To restart a guest Network, click the "Restart Network" button. Please note + all services provided by this Network will be interrupted. When you enable "Clean up", + the virtual routers of guest Network will be destroyed and new virtual routers will + be provisioned. diff --git a/source/adminguide/networking/multiple_guest_networks.rst b/source/adminguide/networking/multiple_guest_networks.rst index f7900cd689..6b8b3b8d70 100644 --- a/source/adminguide/networking/multiple_guest_networks.rst +++ b/source/adminguide/networking/multiple_guest_networks.rst @@ -22,12 +22,12 @@ traffic may be added at any time after the initial installation. You can also customize the domain name associated with the network by specifying a DNS suffix for each network. -A VM's networks are defined at VM creation time. A VM cannot add or +A instance's networks are defined at instance creation time. An instance cannot add or remove networks after it has been created, although the user can go into the guest and remove the IP address from the NIC on a particular network. -Each VM has just one default network. The virtual router's DHCP reply +Each instance has just one default network. The virtual router's DHCP reply will set the guest's default gateway as that for the default network. Multiple non-default networks may be added to a guest in addition to the single, required default network. The administrator can control which @@ -35,7 +35,7 @@ networks are available as the default network. Additional networks can either be available to all accounts or be assigned to a specific account. Networks that are available to all -accounts are zone-wide. Any user with access to the zone can create a VM +accounts are zone-wide. Any user with access to the zone can create an instance with access to that network. These zone-wide networks provide little or no isolation between guests.Networks that are assigned to a specific account provide strong isolation. @@ -72,11 +72,11 @@ Adding an Additional Guest Network #. Click Create. -Reconfiguring Networks in VMs +Reconfiguring Networks in instances ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack provides you the ability to move VMs between networks and -reconfigure a VM's network. You can remove a VM from a network and add +CloudStack provides you the ability to move instances between networks and +reconfigure an instance's network. You can remove an instance from a network and add to a new network. You can also change the default network of a virtual machine. With this functionality, hybrid or traditional server loads can be accommodated with ease. @@ -87,7 +87,7 @@ This feature is supported on XenServer, VMware, and KVM hypervisors. Prerequisites ^^^^^^^^^^^^^ -Ensure that vm-tools are running on guest VMs for adding or removing +Ensure that vm-tools are running on Guest Instances for adding or removing networks to work on VMware hypervisor. @@ -98,16 +98,16 @@ Adding a Network #. In the left navigation, click Instances. -#. Choose the VM that you want to work with. +#. Choose the instance that you want to work with. #. Click the NICs tab. -#. Click Add network to VM. +#. Click Add network to instance. - The Add network to VM dialog is displayed. + The Add network to instance dialog is displayed. #. In the drop-down list, select the network that you would like to add - this VM to. + this instance to. A new NIC is added for this network. You can view the following details in the NICs page: @@ -136,7 +136,7 @@ Removing a Network #. In the left navigation, click Instances. -#. Choose the VM that you want to work with. +#. Choose the instance that you want to work with. #. Click the NICs tab. @@ -154,7 +154,7 @@ Selecting the Default Network #. In the left navigation, click Instances. -#. Choose the VM that you want to work with. +#. Choose the instance that you want to work with. #. Click the NICs tab. @@ -174,7 +174,7 @@ associated with an existing guest network. #. If you are changing from a network offering that uses the CloudStack virtual router to one that uses external devices as network service - providers, you must first stop all the VMs on the network. + providers, you must first stop all the instances on the network. #. In the left navigation, choose Network. @@ -193,10 +193,10 @@ associated with an existing guest network. network device as provider, acknowledge the change of CIDR to continue, so choose Yes. -#. Wait for the update to complete. Don't try to restart VMs until the +#. Wait for the update to complete. Don't try to restart instances until the network change is complete. -#. If you stopped any VMs, restart them. +#. If you stopped any instances, restart them. .. |remove-nic.png| image:: /_static/images/remove-nic.png diff --git a/source/adminguide/networking/multiple_ips_on_single_nic.rst b/source/adminguide/networking/multiple_ips_on_single_nic.rst index 8cd7fb7c11..3082c9bd4e 100644 --- a/source/adminguide/networking/multiple_ips_on_single_nic.rst +++ b/source/adminguide/networking/multiple_ips_on_single_nic.rst @@ -18,15 +18,15 @@ Configuring Multiple IP Addresses on a Single NIC ------------------------------------------------- CloudStack provides you the ability to associate multiple private IP -addresses per guest VM NIC. In addition to the primary IP, you can -assign additional IPs to the guest VM NIC. This feature is supported on +addresses per Guest Instance NIC. In addition to the primary IP, you can +assign additional IPs to the Guest Instance NIC. This feature is supported on all the network configurations: Basic, Advanced, and VPC. Security Groups, Static NAT and Port forwarding services are supported on these additional IPs. As always, you can specify an IP from the guest subnet; if not -specified, an IP is automatically picked up from the guest VM subnet. -You can view the IPs associated with for each guest VM NICs on the UI. +specified, an IP is automatically picked up from the Guest Instance subnet. +You can view the IPs associated with for each Guest Instance NICs on the UI. You can apply NAT on these additional guest IPs by using network configuration option in the CloudStack UI. You must specify the NIC to which the IP should be associated. @@ -57,10 +57,10 @@ Guidelines ~~~~~~~~~~ To prevent IP conflict, configure different subnets when multiple -networks are connected to the same VM. +networks are connected to the same instance. -Assigning Additional IPs to a VM +Assigning Additional IPs to an instance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Log in to the CloudStack UI. @@ -76,9 +76,9 @@ Assigning Additional IPs to a VM #. Click Acquire New Secondary IP, and click Yes in the confirmation dialog. - You need to configure the IP on the guest VM NIC manually. CloudStack - will not automatically configure the acquired IP address on the VM. - Ensure that the IP address configuration persist on VM reboot. + You need to configure the IP on the Guest Instance NIC manually. CloudStack + will not automatically configure the acquired IP address on the instance. + Ensure that the IP address configuration persist on instance reboot. Within a few moments, the new IP address should appear with the state Allocated. You can now use the IP address in Port Forwarding or @@ -94,5 +94,5 @@ default is the primary IP. To enable this functionality, an extra optional parameter 'vmguestip' is added to the Port forwarding and StaticNAT APIs (enableStaticNat, createIpForwardingRule) to indicate on what IP address NAT need to be configured. If vmguestip is passed, NAT -is configured on the specified private IP of the VM. if not passed, NAT -is configured on the primary IP of the VM. +is configured on the specified private IP of the instance. if not passed, NAT +is configured on the primary IP of the instance. diff --git a/source/adminguide/networking/multiple_subnets_in_shared_network.rst b/source/adminguide/networking/multiple_subnets_in_shared_network.rst index d172757681..07936f0432 100644 --- a/source/adminguide/networking/multiple_subnets_in_shared_network.rst +++ b/source/adminguide/networking/multiple_subnets_in_shared_network.rst @@ -75,26 +75,28 @@ Adding Multiple Subnets to a Shared Network All the fields are mandatory. - - **Gateway**: The gateway for the tier you create. Ensure that the + - **Gateway**: The gateway for the Network Tier you create. Ensure that the gateway is within the Super CIDR range that you specified while creating the VPC, and is not overlapped with the CIDR of any - existing tier within the VPC. + existing Network Tier within the VPC. - - **Netmask**: The netmask for the tier you create. + - **Netmask**: The netmask for the Network Tier you create. - For example, if the VPC CIDR is 10.0.0.0/16 and the network tier - CIDR is 10.0.1.0/24, the gateway of the tier is 10.0.1.1, and the - netmask of the tier is 255.255.255.0. + For example, if the VPC CIDR is 10.0.0.0/16 and the Network Tier + CIDR is 10.0.1.0/24, the gateway of the Network Tier is 10.0.1.1, and the + netmask of the Network Tier is 255.255.255.0. - **Start IP/ End IP**: A range of IP addresses that are accessible - from the Internet and will be allocated to guest VMs. Enter the + from the Internet and will be allocated to Guest Instances. Enter the first and last IP addresses that define a range that CloudStack - can assign to guest VMs. + can assign to Guest Instances. - **VLAN/VNI**: the ID or VID of the VLAN. If not specified, will be defaulted to the vlan of the network or if vlan of the network is null - to Untagged +.. note:: If the VNI is of a VXLAN, the protocol prefix `vxlan://` must be used, like in `vxlan://` + #. Click OK. diff --git a/source/adminguide/networking/network_permissions.rst b/source/adminguide/networking/network_permissions.rst new file mode 100644 index 0000000000..1a230fc2cf --- /dev/null +++ b/source/adminguide/networking/network_permissions.rst @@ -0,0 +1,80 @@ +.. 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. + + +Guest Network Permissions +----------------------------- + +From Apache CloudStack 4.17.0.0, guest Networks can be shared to other +accounts in the same domain by managing Network permissions. + +The following Networks can be shared: + +#. L2 Networks not in Project + +#. Isolated Networks not in Project + +#. Shared Networks with scope is Account + +Adding a Network permission +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Network. + +#. In the Select view, select Guest Networks. + +#. Select the guest Network you want to work with. + +#. Click the Network Permissions tab. + + All the Network permissions that you have created for the Network are + listed in the page. |network-permissions.png| + +#. Click Add Network Permission icon. Provide the following information: + + - **Account**: The name of the accounts this Network will be shared to. + + - **Project**. The name of the projects this Network will be shared to. + +#. Click OK. + + .. note:: + The accounts/projects are permitted to create Instances on the Network. + However, they are not permitted to restart and update Network, and + modify Network rules (e.g. firewall, static nat, load balancer, port + forwarding). + + +Removing a Network permission +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To remove a Network permission, click the Delete Network Permission icon of +the Network permission. |delete-button.png| + + +Resetting Network permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack provides the ability to reset the Network permissions of a Network. +All Network permissions will be removed. To reset the Network permission, click +the Reset Network Permissions button on the page. + + +.. |network-permissions.png| image:: /_static/images/network-permissions.png + :alt: network permissions. +.. |delete-button.png| image:: /_static/images/delete-button.png + :alt: button to delete. diff --git a/source/adminguide/networking/persistent_networks.rst b/source/adminguide/networking/persistent_networks.rst index 99eab71cde..f981f1dedb 100644 --- a/source/adminguide/networking/persistent_networks.rst +++ b/source/adminguide/networking/persistent_networks.rst @@ -17,26 +17,26 @@ Persistent Networks ------------------- -The network that you can provision without having to deploy any VMs on +The network that you can provision without having to deploy any instances on it is called a persistent network. A persistent network can be part of a VPC or a non-VPC environment. When you create other types of network, a network is only a database -entry until the first VM is created on that network. When the first VM +entry until the first instance is created on that network. When the first instance is created, a VLAN ID is assigned and the network is provisioned. Also, -when the last VM is destroyed, the VLAN ID is released and the network +when the last instance is destroyed, the VLAN ID is released and the network is no longer available. With the addition of persistent network, you will have the ability to create a network in CloudStack in which -physical devices can be deployed without having to run any VMs. +physical devices can be deployed without having to run any instances. Additionally, you can deploy physical devices on that network. One of the advantages of having a persistent network is that you can -create a VPC with a tier consisting of only physical devices. For -example, you might create a VPC for a three-tier application, deploy VMs +create a VPC with a Network Tier consisting of only physical devices. For +example, you might create a VPC for a three-tier application, deploy instances for Web and Application tier, and use physical machines for the Database tier. Another use case is that if you are providing services by using physical hardware, you can define the network as persistent and -therefore even if all its VMs are destroyed the services will not be +therefore even if all its instances are destroyed the services will not be discontinued. @@ -63,15 +63,15 @@ Persistent Network Considerations - An existing network can be made persistent by changing its network offering to an offering that has the Persistent option enabled. While - setting this property, even if the network has no running VMs, the + setting this property, even if the network has no running instances, the network is provisioned. - An existing network can be made non-persistent by changing its network offering to an offering that has the Persistent option - disabled. If the network has no running VMs, during the next network + disabled. If the network has no running instances, during the next network garbage collection run the network is shut down. -- When the last VM on a network is destroyed, the network garbage +- When the last instance on a network is destroyed, the network garbage collector checks if the network offering associated with the network is persistent, and shuts down the network only if it is non-persistent. diff --git a/source/adminguide/networking/portable_ips.rst b/source/adminguide/networking/portable_ips.rst index a65ca05d9c..0bf0435849 100644 --- a/source/adminguide/networking/portable_ips.rst +++ b/source/adminguide/networking/portable_ips.rst @@ -76,9 +76,9 @@ Configuring Portable IPs #. Specify the following: - **Start IP/ End IP**: A range of IP addresses that are accessible - from the Internet and will be allocated to guest VMs. Enter the + from the Internet and will be allocated to Guest Instances. Enter the first and last IP addresses that define a range that CloudStack - can assign to guest VMs. + can assign to Guest Instances. - **Gateway**: The gateway in use for the Portable IP addresses you are configuring. @@ -129,7 +129,7 @@ API: http://localhost:8096/client/api?command=enableStaticNat&response=json&ipaddressid=a4bc37b2-4b4e-461d-9a62-b66414618e36&virtualmachineid=a242c476-ef37-441e-9c7b-b303e2a9cb4f&networkid=6e7cd8d1-d1ba-4c35-bdaf-333354cbd49810 Replace the UUID with appropriate UUID. For example, if you want to -transfer a portable IP to network X and VM Y in a network, execute the +transfer a portable IP to network X and instance Y in a network, execute the following: .. code:: bash diff --git a/source/adminguide/networking/remote_access_vpn.rst b/source/adminguide/networking/remote_access_vpn.rst index 5b4f15ed2d..95384c27cc 100644 --- a/source/adminguide/networking/remote_access_vpn.rst +++ b/source/adminguide/networking/remote_access_vpn.rst @@ -19,8 +19,8 @@ Remote Access VPN ----------------- -CloudStack account owners can create virtual private networks (VPN) to -access their virtual machines. If the guest network is instantiated from +CloudStack Account owners can create virtual private networks (VPN) to +access their Instances. If the guest network is instantiated from a network offering that offers the Remote Access VPN service, the virtual router (based on the System VM) is used to provide the service. CloudStack provides a L2TP-over-IPsec-based remote access VPN service to @@ -96,7 +96,7 @@ Configuring Remote Access VPN in VPC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On enabling Remote Access VPN on a VPC, any VPN client present outside -the VPC can access VMs present in the VPC by using the Remote VPN +the VPC can access instances present in the VPC by using the Remote VPN connection. The VPN client can be present anywhere except inside the VPC on which the user enabled the Remote Access VPN service. @@ -113,7 +113,7 @@ To enable VPN for a VPC: #. Click the Configure button of the VPC. - For each tier, the following options are displayed: + For each Network Tier, the following options are displayed: - Internal LB @@ -121,7 +121,7 @@ To enable VPN for a VPC: - Static NAT - - Virtual Machines + - Instances - CIDR @@ -133,7 +133,7 @@ To enable VPN for a VPC: - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. In the Router node, select Public IP Addresses. @@ -156,4 +156,19 @@ Now, you need to add the VPN users. #. Click Add. -#. Repeat the same steps to add the VPN users. \ No newline at end of file +#. Repeat the same steps to add the VPN users. + +Limitations of Remote Access VPN +-------------------------------- + +CloudStack's Remote Access VPN feature (L2TP over IPsec with pre-shared key) is subject to certain limitations: + +- **Single connection per source IP/CIDR:** + Due to the use of StrongSwan in the virtual router implementation, CloudStack does not support multiple simultaneous VPN connections originating from the same source public IP or NAT'ed subnet. + This means that if multiple users are behind the same NAT (e.g., office network or shared IP), only one of them can connect at a time. Additional connection attempts will fail until the first session is disconnected. + +- **No support for overlapping subnets by the VPN:** + Remote Access VPN does not provide NAT traversal or address translation features to handle overlapping subnets between the client and the VPC. + +**Recommendation:** +If your environment requires multiple concurrent VPN connections from the same location (NAT or IP), consider deploying a dedicated VPN appliance (e.g., OpenVPN or pfSense) inside the VPC to support advanced use cases. diff --git a/source/adminguide/networking/reserving_an_ip_address.rst b/source/adminguide/networking/reserving_an_ip_address.rst new file mode 100644 index 0000000000..26542f805b --- /dev/null +++ b/source/adminguide/networking/reserving_an_ip_address.rst @@ -0,0 +1,69 @@ +.. 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. + + +Reserving a Public IP Address +----------------------- + +When a public IP address is Free, you can reserve the public IP address. +The public IP address can be reserved to the caller or other accounts. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Network. + +#. Click Public IP Addresses. By default, it displays the Public IP Addresses + in Allocate state. + +#. Filter the Public IP Addresses by state 'Free' + +#. Click the Public IP address you want to reserve. + +#. Click the Reserve IP button. + + The Reserve Public IP dialog is displayed. + +#. In the drop-down list, select the Account Type (Account or Project), Domain, + and Account or Project that you would like to reserve this Public IP to. + +#. Click Submit button. + + Reserved Public IP Addresses can be acquired and used in isolated Networks + or VPCs of the accounts which the Public IP Addresses are reserved to. + + Reserved Public IP Addresses will be considered as an used Public IP of + the account and domain. + +Releasing a Reserved Public IP Address +----------------------- + +When a public IP address is Reserved, you can release the public IP address so +that the public IP address is ready for use by other accounts. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Network. + +#. Click Public IP Addresses. By default, it displays the Public IP Addresses + in Allocate state. + +#. Filter the Public IP Addresses by state 'Reserved' + +#. Click the Public IP address you want to release. + +#. Click the Release IP button. + +#. Click OK button. + diff --git a/source/adminguide/networking/security_groups.rst b/source/adminguide/networking/security_groups.rst index a82ced9627..241ef1c1ff 100644 --- a/source/adminguide/networking/security_groups.rst +++ b/source/adminguide/networking/security_groups.rst @@ -20,33 +20,33 @@ Security Groups About Security Groups ~~~~~~~~~~~~~~~~~~~~~ -Security groups provide a way to isolate traffic to VMs. A security -group is a group of VMs that filter their incoming and outgoing traffic +Security groups provide a way to isolate traffic to instances. A security +group is a group of instances that filter their incoming and outgoing traffic according to a set of rules, called ingress and egress rules. These rules filter network traffic according to the IP address that is -attempting to communicate with the VM. Security groups are particularly +attempting to communicate with the instance. Security groups are particularly useful in zones that use basic networking, because there is a single -guest network for all guest VMs. In advanced zones, security groups are -supported only on the KVM hypervisor. +guest network for all Guest Instances. In advanced zones, security groups are +supported only on the KVM hypervisor and XenServer/XCP-ng with the network backend +configured as "bridge". .. note:: In a zone that uses advanced networking, you can instead define - multiple guest networks to isolate traffic to VMs. + multiple guest networks to isolate traffic to instances. Each CloudStack account comes with a default security group that denies all inbound traffic and allows all outbound traffic. The default -security group can be modified so that all new VMs inherit some other +security group can be modified so that all new instances inherit some other desired set of rules. Any CloudStack user can set up any number of additional security groups. -When a new VM is launched, it is assigned to the default security group -unless another user-defined security group is specified. A VM can be a -member of any number of security groups. Once a VM is assigned to a -security group, it remains in that group for its entire lifetime; you -can not move a running VM from one security group to another. +When a new instance is launched, it is assigned to the default security group +unless another user-defined security group is specified. An instance can be a +member of any number of security groups. You can change the security groups of an instance only in a stopped state; you +can not move a running instance from one security group to another. You can modify a security group by deleting or adding any number of -ingress and egress rules. When you do, the new rules apply to all VMs in +ingress and egress rules. When you do, the new rules apply to all instances in the group, whether running or stopped. If no ingress rules are specified, then no traffic will be allowed in, @@ -115,9 +115,12 @@ In order for security groups to function in a zone, the security groups feature must first be enabled for the zone. The administrator can do this when creating a new zone, by selecting a network offering that includes security groups. The procedure is described in Basic Zone -Configuration in the Advanced Installation Guide. The administrator can -not enable security groups for an existing zone, only when creating a -new zone. +Configuration in the Advanced Installation Guide. + +To enable security groups for an existing advanced zone which doesn't have +security groups enabled, the administrator can enable the +`SecurityGroupProvider` for the physical network of the zone. This will allow +user to create networks with Security Groups. Adding Ingress and Egress Rules to a Security Group @@ -131,7 +134,7 @@ Adding Ingress and Egress Rules to a Security Group you want. #. To add an ingress rule, click the Ingress Rules tab and fill out the - following fields to specify what network traffic is allowed into VM + following fields to specify what network traffic is allowed into instance instances in this security group. If no ingress rules are specified, then no traffic will be allowed in, except for responses to any traffic that has been allowed out through an egress rule. @@ -139,7 +142,7 @@ Adding Ingress and Egress Rules to a Security Group - **Add by CIDR/Account**. Indicate whether the source of the traffic will be defined by IP address (CIDR) or an existing security group in a CloudStack account (Account). Choose Account - if you want to allow incoming traffic from all VMs in another + if you want to allow incoming traffic from all instances in another security group - **Protocol**. The networking protocol that sources will use to @@ -164,7 +167,7 @@ Adding Ingress and Egress Rules to a Security Group - **Account, Security Group**. (Add by Account only) To accept only traffic from another security group, enter the CloudStack account and name of a security group that has already been defined in that - account. To allow traffic between VMs within the security group + account. To allow traffic between instances within the security group you are editing now, enter the same name you used in step 7. The following example allows inbound HTTP access from anywhere: @@ -173,7 +176,7 @@ Adding Ingress and Egress Rules to a Security Group #. To add an egress rule, click the Egress Rules tab and fill out the following fields to specify what type of traffic is allowed to be - sent out of VM instances in this security group. If no egress rules + sent out of instances in this security group. If no egress rules are specified, then all traffic will be allowed out. Once egress rules are specified, the following types of traffic are allowed out: traffic specified in egress rules; queries to DNS and DHCP servers; @@ -183,10 +186,10 @@ Adding Ingress and Egress Rules to a Security Group - **Add by CIDR/Account**. Indicate whether the destination of the traffic will be defined by IP address (CIDR) or an existing security group in a CloudStack account (Account). Choose Account - if you want to allow outgoing traffic to all VMs in another + if you want to allow outgoing traffic to all instances in another security group. - - **Protocol**. The networking protocol that VMs will use to send + - **Protocol**. The networking protocol that instances will use to send outgoing traffic. TCP and UDP are typically used for data exchange and end-user communications. ICMP is typically used to send error messages or network monitoring data. @@ -207,7 +210,7 @@ Adding Ingress and Egress Rules to a Security Group - **Account, Security Group**. (Add by Account only) To allow traffic to be sent to another security group, enter the CloudStack account and name of a security group that has already been defined - in that account. To allow traffic between VMs within the security + in that account. To allow traffic between instances within the security group you are editing now, enter its name. #. Click Add. diff --git a/source/adminguide/networking/site_to_site_vpn.rst b/source/adminguide/networking/site_to_site_vpn.rst index 15224f1f66..7bf09767ae 100644 --- a/source/adminguide/networking/site_to_site_vpn.rst +++ b/source/adminguide/networking/site_to_site_vpn.rst @@ -20,12 +20,12 @@ Setting Up a Site-to-Site VPN Connection A Site-to-Site VPN connection helps you establish a secure connection from an enterprise datacenter to the cloud infrastructure. This allows -users to access the guest VMs by establishing a VPN connection to the +users to access the Guest Instances by establishing a VPN connection to the virtual router of the account from a device in the datacenter of the enterprise. You can also establish a secure connection between two VPC setups or high availability zones in your environment. Having this facility eliminates the need to establish VPN connections to individual -VMs. +instances. The difference from Remote VPN is that Site-to-site VPNs connects entire networks to each other, for example, connecting a branch office network @@ -64,7 +64,7 @@ Creating and Updating a VPN Customer Gateway ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: - A VPN customer gateway can be connected to only one VPN gateway at a time. + A VPN Customer Gateway can be connected to only one VPN gateway at a time. To add a VPN Customer Gateway: @@ -80,7 +80,7 @@ To add a VPN Customer Gateway: Provide the following information: - - **Name**: A unique name for the VPN customer gateway you create. + - **Name**: A unique name for the VPN Customer Gateway you create. - **Gateway**: The IP address for the remote gateway. @@ -115,13 +115,19 @@ To add a VPN Customer Gateway: confirming that the remote gateway has a matching Preshared Key. - **IKE Hash**: The IKE hash for phase-1. The supported hash - algorithms are SHA1 and MD5. + algorithms are SHA1, SHA256, SHA384 and SHA512 and MD5. + + - **IKE Version**: The IKE Version to use between ike (autoselect), ikev1, or ikev2. + Connections marked with 'ike' will use 'ikev2' when initiating, + but accept any protocol version when responding. Defaults to 'ike'. - **IKE DH**: A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The 1536-bit Diffie-Hellman group is used within IKE to establish session keys. The supported options are - None, Group-5 (1536-bit) and Group-2 (1024-bit). + None, Group-2 (1024-bit), Group-5 (1536-bit), Group-14 (2048-bit), + Group-15 (3072-bit), Group-16 (4096-bit), Group-17 (6144-bit) and + Group-18 (8192-bit). - **ESP Encryption**: Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, @@ -134,8 +140,8 @@ To add a VPN Customer Gateway: extracted from the Diffie-Hellman key exchange in phase-1, to provide session keys to use in protecting the VPN data flow. - - **ESP Hash**: Encapsulating Security Payload (ESP) hash for - phase-2. Supported hash algorithms are SHA1 and MD5. + - **ESP Hash**: Encapsulating Security Payload (ESP) hash for phase-2. + Supported hash algorithms are SHA1, SHA256, SHA384 and SHA512 and MD5. - **Perfect Forward Secrecy**: Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of @@ -143,9 +149,10 @@ To add a VPN Customer Gateway: property enforces a new Diffie-Hellman key exchange. It provides the keying material that has greater key material life and thereby greater resistance to cryptographic attacks. The available options - are None, Group-5 (1536-bit) and Group-2 (1024-bit). The security - of the key exchanges increase as the DH groups grow larger, as - does the time of the exchanges. + are None, Group-2 (1024-bit), Group-5 (1536-bit), Group-14 (2048-bit), + Group-15 (3072-bit), Group-16 (4096-bit), Group-17 (6144-bit) and + Group-18 (8192-bit). The security of the key exchanges increase as + the DH groups grow larger, as does the time of the exchanges. .. note:: When PFS is turned on, for every negotiation of a new phase-2 SA @@ -172,27 +179,137 @@ To add a VPN Customer Gateway: - **Force UDP Encapsulation of ESP Packets**: Force Encapsulation for NAT traversal + .. note:: + If the administrator has configured excluded cryptographic + parameters, those options will not appear in the form. If obsolete + parameters are configured, those options will be displayed with a + warning message indicating they are obsolete and should be avoided. + #. Click OK. +Configuring Excluded and Obsolete VPN Customer Gateway Parameters +'''''''''''''''''''''''''''''''''''''''''''''''' + +CloudStack provides administrators with configuration settings to enforce +modern security standards by marking certain cryptographic algorithms and +parameters as excluded or obsolete for VPN Customer Gateway creation. + +**Excluded Parameters:** + +These parameters are completely hidden from users and cannot be used +while creating or updating VPN Customer Gateways: + +- **vpn.customer.gateway.excluded.encryption.algorithms**: Comma-separated + list of encryption algorithms to exclude. Applies to both phases. + +- **vpn.customer.gateway.excluded.hashing.algorithms**: Comma-separated + list of hashing algorithms to exclude. Applies to both phases. + +- **vpn.customer.gateway.excluded.ike.versions**: Comma-separated list of + IKE versions to exclude. + +- **vpn.customer.gateway.excluded.dh.group**: Comma-separated list of + Diffie-Hellman groups to exclude. Applies to both phases. + +**Obsolete Parameters:** + +These parameters are shown with a warning message, allowing existing +deployments to continue functioning while encouraging migration to more +secure alternatives: + +- **vpn.customer.gateway.obsolete.encryption.algorithms**: Comma-separated + list of encryption algorithms marked as obsolete. Applies to both phases. + +- **vpn.customer.gateway.obsolete.hashing.algorithms**: Comma-separated + list of hashing algorithms marked as obsolete. Applies to phases. + +- **vpn.customer.gateway.obsolete.ike.versions**: Comma-separated list of + IKE versions marked as obsolete. + +- **vpn.customer.gateway.obsolete.dh.group**: Comma-separated list of + Diffie-Hellman groups marked as obsolete. Applies to both phases. + +**Behavior:** + +- **Excluded parameters**: Not shown in the Create and Update VPN Customer + Gateway forms. Users cannot select these options for new gateways. + +- **Obsolete parameters**: Shown with a warning message in the Create and + Update forms, indicating they are deprecated and should be avoided. + +- **Existing gateways**: If a VPN Customer Gateway already uses excluded or + obsolete parameters: + + - A warning icon is displayed next to the gateway name with a message + prompting users to change the obsolete or excluded parameters. + + - The Update VPN Customer Gateway form displays the setting with a + warning message encouraging users to change it to a more secure + alternative. + +- The ``listVpnCustomerGateways`` API response includes two new fields: + + - **obsoleteparameters**: List of all obsolete parameters used by the gateway + + - **excludedparameters**: List of all excluded parameters used by the gateway + +- The ``listCapabilities`` API response includes a new field containing + the list of excluded and obsolete VPN Customer Gateway parameters, but + only if these configuration settings are configured by the operator. + +**Events and Alerts:** + +There is a thread that run periodically to check for VPN Customer Gateways which +are using excluded or obsolete cryptographic parameters.The interval at which this thread +runs is configurable using the setting **vpn.customer.gateway.obsolete.check.interval**. +The unit is in hours and the default value is 0 which means it is disabled by default. + +Each time the thread runs, it generates Events for each VPN Customer Gateway which is +using excluded or obsolete parameters. +It also generates Alerts to the Administrator about the number of VPN Customer Gateways +that are using excluded and/or obsolete parameters. + +**Configuration Scope:** + +The obsolete and excluded settings support Domain-level configuration. +When set at Domain level, the values override global settings for that specific Domain only. + +- Global Settings: Apply to all Domains without specific overrides + +- Domain Settings: Override global settings for that specific Domain only + +Note: Domain settings do not cascade to child Domains. Each child Domain must be configured individually, +or it will inherit from global settings (not from its parent Domain). + +To reset a Domain-specific override, navigate to Domains → [Domain Name] → Settings and reset the value. +This will cause the Domain to fall back to global settings + Updating and Removing a VPN Customer Gateway '''''''''''''''''''''''''''''''''''''''''''' You can update a customer gateway either with no VPN connection, or related VPN connection is in error state. +.. note:: + If a VPN Customer Gateway is using excluded or obsolete cryptographic + parameters (as configured by your CloudStack operator), a warning icon + will be displayed next to the gateway name. When editing such a gateway, + the Update form will display warnings for any obsolete or excluded + parameters, encouraging you to change them to more secure alternatives. + #. Log in to the CloudStack UI as an administrator or end user. #. In the left navigation, choose Network. #. In the Select view, select VPN Customer Gateway. -#. Select the VPN customer gateway you want to work with. +#. Select the VPN Customer Gateway you want to work with. #. To modify the required parameters, click the Edit VPN Customer Gateway button |vpn-edit-icon.png| -#. To remove the VPN customer gateway, click the Delete VPN Customer +#. To remove the VPN Customer Gateway, click the Delete VPN Customer Gateway button |delete.png| #. Click OK. @@ -211,12 +328,12 @@ Creating a VPN gateway for the VPC page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + instances. - The VPC page is displayed where all the tiers you created are listed + The VPC page is displayed where all the Network Tiers you created are listed in a diagram. - For each tier, the following options are displayed: + For each Network Tier, the following options are displayed: - Internal LB @@ -224,7 +341,7 @@ Creating a VPN gateway for the VPC - Static NAT - - Virtual Machines + - Instances - CIDR @@ -236,7 +353,7 @@ Creating a VPN gateway for the VPC - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select Site-to-Site VPN. @@ -272,14 +389,14 @@ Creating a VPN Connection All the VPCs that you create for the account are listed in the page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + instances. - The VPC page is displayed where all the tiers you created are listed + The VPC page is displayed where all the Network Tiers you created are listed in a diagram. #. Click the Settings icon. - For each tier, the following options are displayed: + For each Network Tier, the following options are displayed: - Internal LB @@ -287,7 +404,7 @@ Creating a VPN Connection - Static NAT - - Virtual Machines + - Instances - CIDR @@ -299,7 +416,7 @@ Creating a VPN Connection - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select Site-to-Site VPN. @@ -364,7 +481,7 @@ This feature is supported on all the hypervisors. For more information, see `"Creating a VPN gateway for the VPC" <#creating-a-vpn-gateway-for-the-vpc>`_. -#. Create VPN customer gateway for both the VPCs. +#. Create VPN Customer Gateway for both the VPCs. For more information, see `"Creating and Updating a VPN Customer Gateway" <#creating-and-updating-a-vpn-customer-gateway>`_. @@ -404,14 +521,14 @@ Restarting and Removing a VPN Connection page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + instances. - The VPC page is displayed where all the tiers you created are listed + The VPC page is displayed where all the Network Tiers you created are listed in a diagram. #. Click the Settings icon. - For each tier, the following options are displayed: + For each Network Tier, the following options are displayed: - Internal LB @@ -419,7 +536,7 @@ Restarting and Removing a VPN Connection - Static NAT - - Virtual Machines + - Instances - CIDR @@ -431,7 +548,7 @@ Restarting and Removing a VPN Connection - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select Site-to-Site VPN. @@ -464,6 +581,6 @@ Restarting and Removing a VPN Connection .. |reset-vpn.png| image:: /_static/images/reset-vpn.png :alt: button to reset a VPN connection .. |delete.png| image:: /_static/images/delete-button.png - :alt: button to remove a VPN customer gateway. + :alt: button to remove a VPN Customer Gateway. .. |vpn-edit-icon.png| image:: /_static/images/edit-icon.png :alt: button to edit. diff --git a/source/adminguide/networking/static_nat.rst b/source/adminguide/networking/static_nat.rst index 6e57b36e3c..83dc2933d1 100644 --- a/source/adminguide/networking/static_nat.rst +++ b/source/adminguide/networking/static_nat.rst @@ -18,7 +18,7 @@ Static NAT ---------- A static NAT rule maps a public IP address to the private IP address of -a VM in order to allow Internet traffic into the VM. The public IP +an instance in order to allow Internet traffic into the instance. The public IP address always remains the same, which is why it is called static NAT. This section tells how to enable or disable static NAT for a particular IP address. @@ -30,7 +30,7 @@ Enabling or Disabling Static NAT If port forwarding rules are already in effect for an IP address, you cannot enable static NAT to that IP. -If a guest VM is part of more than one network, static NAT rules will +If a Guest Instance is part of more than one network, static NAT rules will function only if they are defined on the default network. #. Log in to the CloudStack UI as an administrator or end user. @@ -49,7 +49,7 @@ function only if they are defined on the default network. static NAT is currently enabled for the IP address. #. If you are enabling static NAT, a dialog appears where you can choose - the destination VM and click Apply. + the destination instance and click Apply. .. |enabledisablenat.png| image:: /_static/images/enable-disable.png diff --git a/source/adminguide/networking/using_remote_access.rst b/source/adminguide/networking/using_remote_access.rst index 2161abe74a..9c30a33e0d 100644 --- a/source/adminguide/networking/using_remote_access.rst +++ b/source/adminguide/networking/using_remote_access.rst @@ -24,9 +24,9 @@ Using Remote Access VPN :local: :depth: 1 -Remote Access VPN connection to VPC or Guest Network to access Instances and applications. This section consider you have enable Remonte acccess VPN, refer to: :ref:`remote-access-vpn`. +Remote Access VPN connection to VPC or Guest Network to access Instances and applications. This section considers you have enabled Remote access VPN, refer to: :ref:`remote-access-vpn`. -When connected to a VPC via VPN, the client have access to all Tiers. +When connected to a VPC via VPN, the client have access to all Network Tiers. Following information is required to confiture VPN client: diff --git a/source/adminguide/networking/virtual_private_cloud_config.rst b/source/adminguide/networking/virtual_private_cloud_config.rst index 5f381d6923..2a2bb57dd4 100644 --- a/source/adminguide/networking/virtual_private_cloud_config.rst +++ b/source/adminguide/networking/virtual_private_cloud_config.rst @@ -25,35 +25,35 @@ About Virtual Private Clouds ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CloudStack Virtual Private Cloud is a private, isolated part of -CloudStack. A VPC can have its own virtual network topology that -resembles a traditional physical network. You can launch VMs in the -virtual network that can have private addresses in the range of your -choice, for example: 10.0.0.0/16. You can define network tiers within -your VPC network range, which in turn enables you to group similar kinds -of instances based on IP address range. +CloudStack. A VPC can have its own virtual Network topology that +resembles a traditional physical Network. You can launch Instances in the +virtual Network that can have private addresses in the range of your +choice, for example: 10.0.0.0/16. You can define Network Tiers within +your VPC Network range, which in turn enables you to group similar kinds +of Instances based on IP address range. For example, if a VPC has the private range 10.0.0.0/16, its guest -networks can have the network ranges 10.0.1.0/24, 10.0.2.0/24, +Networks can have the Network ranges 10.0.1.0/24, 10.0.2.0/24, 10.0.3.0/24, and so on. Major Components of a VPC ^^^^^^^^^^^^^^^^^^^^^^^^^ -A VPC is comprised of the following network components: +A VPC is comprised of the following Network components: -- **VPC**: A VPC acts as a container for multiple isolated networks +- **VPC**: A VPC acts as a container for multiple isolated Networks that can communicate with each other via its virtual router. -- **Network Tiers**: Each tier acts as an isolated network with its own +- **Network Tiers**: Each Network Tier acts as an isolated Network with its own VLANs and CIDR list, where you can place groups of resources, such as - VMs. The tiers are segmented by means of VLANs. The NIC of each tier - acts as its gateway. + Instances. The Network Tiers are segmented by means of VLANs. The NIC of each + Network Tier acts as its gateway. - **Virtual Router**: A virtual router is automatically created and - started when you create a VPC. The virtual router connect the tiers + started when you create a VPC. The virtual router connect the Network Tiers and direct traffic among the public gateway, the VPN gateways, and - the NAT instances. For each tier, a corresponding NIC and IP exist in + the NAT Instances. For each Network Tier, a corresponding NIC and IP exist in the virtual router. The virtual router provides DNS and DHCP services through its IP. @@ -62,35 +62,35 @@ A VPC is comprised of the following network components: not exposed to the end user; therefore, static routes are not support for the public gateway. -- **Private Gateway**: All the traffic to and from a private network +- **Private Gateway**: All the traffic to and from a private Network routed to the VPC through the private gateway. For more information, see ":ref:`adding-priv-gw-vpc`". - **VPN Gateway**: The VPC side of a VPN connection. - **Site-to-Site VPN Connection**: A hardware-based VPN connection - between your VPC and your datacenter, home network, or co-location + between your VPC and your datacenter, home Network, or co-location facility. For more information, see ":ref:`setting-s2s-vpn-conn`". - **Customer Gateway**: The customer side of a VPN Connection. For more information, see `"Creating and Updating a VPN Customer Gateway" <#creating-and-updating-a-vpn-customer-gateway>`_. -- **NAT Instance**: An instance that provides Port Address Translation - for instances to access the Internet via the public gateway. For more +- **NAT Instance**: An Instance that provides Port Address Translation + for Instances to access the Internet via the public gateway. For more information, see ":ref:`enabling-disabling-static-nat-on-vpc`". - **Network ACL**: Network ACL is a group of Network ACL items. Network ACL items are nothing but numbered rules that are evaluated in order, starting with the lowest numbered rule. These rules determine whether - traffic is allowed in or out of any tier associated with the network + traffic is allowed in or out of any Network Tier associated with the Network ACL. For more information, see ":ref:`conf-net-acl`". Network Architecture in a VPC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In a VPC, the following four basic options of network architectures are +In a VPC, the following four basic options of Network architectures are present: - VPC with a public gateway only @@ -126,20 +126,20 @@ Consider the following before you create a VPC: - A VPC can be created in Advance zone only, and can't belong to more than one zone at a time. -- The default number of VPCs an account can create is 20. However, you +- The default number of VPCs an Account can create is 20. However, you can change it by using the max.account.vpcs global parameter, which - controls the maximum number of VPCs an account is allowed to create. + controls the maximum number of VPCs an Account is allowed to create. -- The default number of tiers an account can create within a VPC is 3. +- The default number of Network Tiers an Account can create within a VPC is 3. You can configure this number by using the vpc.max.networks parameter. -- Each tier should have an unique CIDR in the VPC. Ensure that the - tier's CIDR should be within the VPC CIDR range. +- Each Network Tier should have an unique CIDR in the VPC. Ensure that the + Network Tier's CIDR should be within the VPC CIDR range. -- A tier belongs to only one VPC. +- A Network Tier belongs to only one VPC. -- All network tiers inside the VPC should belong to the same account. +- All Network Tiers inside the VPC should belong to the same Account. - When a VPC is created, by default, a SourceNAT IP is allocated to it. The Source NAT IP is released only when the VPC is removed. @@ -147,38 +147,38 @@ Consider the following before you create a VPC: - A public IP can be used for only one purpose at a time. If the IP is a sourceNAT, it cannot be used for StaticNAT or port forwarding. -- The instances can only have a private IP address that you provision. - To communicate with the Internet, enable NAT to an instance that you +- The Instances can only have a private IP address that you provision. + To communicate with the Internet, enable NAT to an Instance that you launch in your VPC. -- Only new networks can be added to a VPC. The maximum number of - networks per VPC is limited by the value you specify in the +- Only new Networks can be added to a VPC. The maximum number of + Networks per VPC is limited by the value you specify in the vpc.max.networks parameter. The default value is three. -- The load balancing service can be supported by only one tier inside - the VPC. +- The load balancing service can be supported by only one Network Tier + inside the VPC. -- If an IP address is assigned to a tier: +- If an IP address is assigned to a Network Tier: - - That IP can't be used by more than one tier at a time in the VPC. - For example, if you have tiers A and B, and a public IP1, you can + - That IP can't be used by more than one Network Tier at a time in the VPC. + For example, if you have Network Tiers A and B, and a public IP1, you can create a port forwarding rule by using the IP either for A or B, but not for both. - That IP can't be used for StaticNAT, load balancing, or port - forwarding rules for another guest network inside the VPC. + forwarding rules for another guest Network inside the VPC. -- Remote access VPN is not supported in VPC networks. +- Remote access VPN is not supported in VPC Networks. Adding a Virtual Private Cloud ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When creating the VPC, you simply provide the zone and a set of IP -addresses for the VPC network address space. You specify this set of +addresses for the VPC Network address space. You specify this set of addresses in the form of a Classless Inter-Domain Routing (CIDR) block. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. @@ -197,92 +197,122 @@ addresses in the form of a Classless Inter-Domain Routing (CIDR) block. - **Zone**: Choose the zone where you want the VPC to be available. - **CIDR**: Defines the CIDR range for all - the tiers (guest networks) within a VPC. When you create a tier, - ensure that its CIDR is within the Super CIDR value you enter. The - CIDR must be RFC1918 compliant. + the Network Tiers (guest Networks) within a VPC. When you create a + Network Tier, ensure that its CIDR is within the Super CIDR value + you enter. The CIDR must be RFC1918 compliant. - **Network Domain**: If you want to assign a special domain name, specify the DNS suffix. This parameter is applied to - all the tiers within the VPC. That implies, all the tiers you - create in the VPC belong to the same DNS domain. If the parameter - is not specified, a DNS domain name is generated automatically. + all the Network Tiers within the VPC. That implies, all the Network + Tiers you create in the VPC belong to the same DNS domain. If the + parameter is not specified, a DNS domain name is generated automatically. - **VPC Offering**: If the administrator has configured multiple - VPC offerings, select the one you want to use for this VPC + VPC offerings, select the one you want to use for this VPC. + + .. note:: + VPC Offerings can now be created with Conserve mode. When Conserve mode is off, the public IP can only be used for a single VPC Network Tier (e.g. you can add VMs from only a single VPC tier/network to the Load Balancer). But when the Conserve mode is on, you can define services (use VMS as targets) from more than one VPC Network Tier on the same public IP (e.g. add VMs1 from Tier1 and VM2 from Tier2 to a single Load Balancer. + + .. note:: + If StaticNAT is enabled, irrespective of the status of the + conserve mode, no port forwarding or load balancing rule can be + created for the IP. However, you can add the firewall rules by + using the createFirewallRule command. + + .. note:: + In case Conserve Mode is enabled on VPC Offering and VPC Network Tier Offerings, then the Source NAT IP address of the VPC can be reused for multiple services. + + + - **DNS**: A set of custom DNS that will be used by this VPC. If not provided then DNS specified for the zone will be used. Available only when the selected VPC offering supports DNS service. + + - **IPv6 DNS**: A set of custom IPv6 DNS that will be used by this VPC. If not provided then IPv6 DNS specified for the zone will be used. Available only when the selected VPC offering is IPv6 enabled and supports DNS service. + + - **IPv4 address for the VR in this VPC**: The source NAT address or primary public Network address to use by the guest Networks. If not provided then a random address from the available pool of addresses will be used. + + - **Public MTU**: The MTU to be configured on the public interfaces of the + VPC Network's VR #. Click OK. +.. note:: + * In security groups-enabled Advanced zones and Basic zones, creation of + VPC and isolated Networks are not supported. + * Public MTU option will be shown in the UI and considered only when zone configuration - `allow.end.users.to.specify.vr.mtu` is set to true. Maximum allowed value for public MTU can be controlled by zone-level configuration - `vr.public.interface.max.mtu`. -Adding Tiers -~~~~~~~~~~~~ +Adding Network Tiers +~~~~~~~~~~~~~~~~~~~~ -Tiers are distinct locations within a VPC that act as isolated networks, -which do not have access to other tiers by default. Tiers are set up on -different VLANs that can communicate with each other by using a virtual -router. Tiers provide inexpensive, low latency network connectivity to -other tiers within the VPC. +Network Tiers are distinct locations within a VPC that act as isolated Networks, +which do not have access to other Network Tiers by default. Network Tiers are +set up on different VLANs that can communicate with each other by using a virtual +router. Network Tiers provide inexpensive, low latency Network connectivity to +other Network Tiers within the VPC. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPC that you have created for the account is listed in the + All the VPC that you have created for the Account is listed in the page. .. note:: - The end users can see their own VPCs, while root and domain admin can + The end Users can see their own VPCs, while root and domain admin can see any VPC they are authorized to see. #. Click the Configure button of the VPC for which you want to set up - tiers. + Network Tiers. -#. Click Create network. +#. Click Create Network. - The Add new tier dialog is displayed, as follows: + The Add new Network Tier dialog is displayed, as follows: |add-tier.png| - If you have already created tiers, the VPC diagram is displayed. - Click Create Tier to add a new tier. + If you have already created Network Tiers, the VPC diagram is displayed. + Click Create Network Tier to add a new Network Tier. #. Specify the following: All the fields are mandatory. - - **Name**: A unique name for the tier you create. + - **Name**: A unique name for the Network Tier you create. + + .. note:: + Admins can choose to automatically prepend the VPC name to the Tier name during creation + using global configurations "vpc.tier.name.prepend" and "vpc.tier.name.prepend.delimiter". - - **Network Offering**: The following default network offerings are + - **Network Offering**: The following default Network offerings are listed: Internal LB, DefaultIsolatedNetworkOfferingForVpcNetworksNoLB, DefaultIsolatedNetworkOfferingForVpcNetworks - In a VPC, only one tier can be created by using LB-enabled network + In a VPC, only one Network Tier can be created by using LB-enabled Network offering. - - **Gateway**: The gateway for the tier you create. Ensure that the + - **Gateway**: The gateway for the Network Tier you create. Ensure that the gateway is within the Super CIDR range that you specified while creating the VPC, and is not overlapped with the CIDR of any - existing tier within the VPC. + existing Network Tier within the VPC. - - **VLAN**: The VLAN ID for the tier that the root admin creates. + - **VLAN**: The VLAN ID for the Network Tier that the root admin creates. - This option is only visible if the network offering you selected + This option is only visible if the Network offering you selected is VLAN-enabled. For more information, see `"Assigning VLANs to Isolated Networks" `_. - - **Netmask**: The netmask for the tier you create. + - **Netmask**: The netmask for the Network Tier you create. - For example, if the VPC CIDR is 10.0.0.0/16 and the network tier - CIDR is 10.0.1.0/24, the gateway of the tier is 10.0.1.1, and the - netmask of the tier is 255.255.255.0. + For example, if the VPC CIDR is 10.0.0.0/16 and the Network Tier + CIDR is 10.0.1.0/24, the gateway of the Network Tier is 10.0.1.1, + and the netmask of the Network Tier is 255.255.255.0. #. Click OK. -#. Continue with configuring access control list for the tier. +#. Continue with configuring access control list for the Network Tier. .. _conf-net-acl: @@ -290,34 +320,22 @@ other tiers within the VPC. Configuring Network Access Control List ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Define Network Access Control List (ACL) on the VPC virtual router to -control incoming (ingress) and outgoing (egress) traffic between the VPC -tiers, and the tiers and Internet. By default, all incoming traffic to -the guest networks is blocked and all outgoing traffic from guest -networks is allowed, once you add an ACL rule for outgoing traffic, then -only outgoing traffic specified in this ACL rule is allowed, the rest is -blocked. To open the ports, you must create a new network ACL. The -network ACLs can be created for the tiers only if the NetworkACL service -is supported. +.. note:: + Network Access Control Lists can only be created if the service + "NetworkACL" is supported by the created VPC. +Define a Network Access Control List (ACL) to control incoming +(ingress) and outgoing (egress) traffic between the associated Network Tier +and external Networks (other Network Tiers of the VPC as well as public Networks). -About Network ACL Lists -^^^^^^^^^^^^^^^^^^^^^^^ +About Network ACLs +^^^^^^^^^^^^^^^^^^ -In CloudStack terminology, Network ACL is a group of Network ACL items. -Network ACL items are nothing but numbered rules that are evaluated in -order, starting with the lowest numbered rule. These rules determine -whether traffic is allowed in or out of any tier associated with the -network ACL. You need to add the Network ACL items to the Network ACL, -then associate the Network ACL with a tier. Network ACL is associated -with a VPC and can be assigned to multiple VPC tiers within a VPC. A -Tier is associated with a Network ACL at all the times. Each tier can be -associated with only one ACL. - -The default Network ACL is used when no ACL is associated. Default -behavior is all the incoming traffic is blocked and outgoing traffic is -allowed from the tiers. Default network ACL cannot be removed or -modified. Contents of the default Network ACL is: +In CloudStack terminology, a Network ACL is a group of Network ACL rules. +Network ACL rules are processed by their order, starting with the lowest +numbered rule. Each rule defines at least an affected protocol, traffic type, +action and affected destination / source Network. The following table shows a +exemplary content of a "default_deny" ACL. .. cssclass:: table-striped table-bordered table-hover @@ -328,17 +346,40 @@ Rule Protocol Traffic type Action CIDR 2 All Egress Deny 0.0.0.0/0 ===== ======== ============ ====== ========= - -Creating ACL Lists -^^^^^^^^^^^^^^^^^^ - -#. Log in to the CloudStack UI as an administrator or end user. +Each Network ACL is associated with a VPC and can be assigned +to multiple VPC Network Tiers. Every Network Tier needs to be associated with a +Network ACL. Only one ACL can be associated with a Network Tier at a time. If no +custom Network ACL is available at the time of Network Tier creation, a default +Network ACL has to be used instead. Currently two default ACL are +available. The "default_allow" ACL allows in- and egress traffic while +the "default_deny" blocks all in- and egress traffic. Default Network +ACL cannot be removed or modified. Newly created ACLs, while showing +empty, deny all incoming traffic to the associated tier and allow all +outgoing traffic. To change the defaults add a "deny all egress +destination" and / or "allow all ingress source" rule to the ACL. +Afterwards traffic can be white- or blacklisted. + +.. note:: + - ACL Rules in Cloudstack are stateful + - Source / Destination CIDRs are always external Networks + - ACL rules can also been seen on the virtual router of the VPC. Ingress + rules are listed in the table iptables table "filter" while egress rules + are placed in the "mangle" table + - ACL rules for ingress and egress are not correlating. For example a + egress "deny all" won't affect traffic in response to an allowed ingress + connection + + +Creating ACLs +^^^^^^^^^^^^^ + +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC. @@ -351,7 +392,7 @@ Creating ACL Lists - Static NAT - - Virtual Machines + - Instances - CIDR @@ -363,18 +404,18 @@ Creating ACL Lists - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs -#. Select Network ACL Lists. +#. Select Network ACLs. The following default rules are displayed in the Network ACLs page: default\_allow, default\_deny. -#. Click Add ACL Lists, and specify the following: +#. Click Add Network ACL, and specify the following: - - **ACL List Name**: A name for the ACL list. + - **ACL Name**: A name for the ACL. - - **Description**: A short description of the ACL list that can be + - **Description**: A short description of the ACL that can be displayed to users. @@ -387,20 +428,20 @@ Creating an ACL Rule #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC. -#. Select Network ACL Lists. +#. Select Network ACLs. - In addition to the custom ACL lists you have created, the following + In addition to the custom ACLs you have created, the following default rules are displayed in the Network ACLs page: default\_allow, default\_deny. -#. Select the desired ACL list. +#. Select the desired ACL. -#. Select the ACL List Rules tab. +#. Select the ACL Rules tab. To add an ACL rule, fill in the following fields to specify what kind of network traffic is allowed in the VPC. @@ -443,24 +484,24 @@ Creating an ACL Rule tab. -Creating a Tier with Custom ACL List -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Creating a Tier with Custom ACL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Create a VPC. -#. Create a custom ACL list. +#. Create a custom ACL. -#. Add ACL rules to the ACL list. +#. Add ACL rules to the ACL. #. Create a tier in the VPC. - Select the desired ACL list while creating a tier. + Select the desired ACL while creating a tier. #. Click OK. -Assigning a Custom ACL List to a Tier -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Assigning a Custom ACL to a Tier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Create a VPC. @@ -468,17 +509,17 @@ Assigning a Custom ACL List to a Tier #. Associate the tier with the default ACL rule. -#. Create a custom ACL list. +#. Create a custom ACL. -#. Add ACL rules to the ACL list. +#. Add ACL rules to the ACL. #. Select the tier for which you want to assign the custom ACL. -#. Click the Replace ACL List icon. |replace-acl-icon.png| +#. Click the Replace ACL icon. |replace-acl-icon.png| - The Replace ACL List dialog is displayed. + The Replace ACL dialog is displayed. -#. Select the desired ACL list. +#. Select the desired ACL. #. Click OK. @@ -488,18 +529,18 @@ Assigning a Custom ACL List to a Tier Adding a Private Gateway to a VPC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A private gateway can be added by the root admin only. The VPC private +A private gateway can be added by the root admin and Users. The VPC private network has 1:1 relationship with the NIC of the physical network. You can configure multiple private gateways to a single VPC. No gateways with duplicated VLAN and IP are allowed in the same data center. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC to which you want to configure @@ -518,7 +559,7 @@ with duplicated VLAN and IP are allowed in the same data center. - Static NAT - - Virtual Machines + - Instances - CIDR @@ -530,7 +571,7 @@ with duplicated VLAN and IP are allowed in the same data center. - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select Private Gateways. @@ -538,14 +579,14 @@ with duplicated VLAN and IP are allowed in the same data center. #. Click Add new gateway: - |add-new-gateway-vpc.png| + |add-new-gateway-vpc2.png| #. Specify the following: - - **Physical Network**: The physical network you have created in the - zone. + - **Physical Network**: (Administrators only) The physical network + you have created in the zone. - - **VLAN**: The VLAN associated with the VPC gateway. + - **VLAN**: (Administrators only) The VLAN associated with the VPC gateway. - **IP Address**: The IP address associated with the VPC gateway. @@ -559,8 +600,13 @@ with duplicated VLAN and IP are allowed in the same data center. See ":ref:`source-nat-priv-gw`". - - **Bypass VLAN id/range overlap**: Bypasses the check for a VLAN - overlap. This way multiple networks with the same VLAN can be created + - **Bypass VLAN id/range overlap**: (Administrators only) Bypasses + the check for a VLAN overlap. This way multiple networks with the + same VLAN can be created + + - **Associated Network**: The L2 or Isolated network this private + gateway is associated to. This private network will use the same + VLAN as the associated network. - **ACL**: Controls both ingress and egress traffic on a VPC private gateway. By default, all the traffic is blocked. @@ -577,11 +623,11 @@ Source NAT on Private Gateway ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You might want to deploy multiple VPCs with the same super CIDR and -guest tier CIDR. Therefore, multiple guest VMs from different VPCs can +guest tier CIDR. Therefore, multiple Guest Instances from different VPCs can have the same IPs to reach a enterprise data center through the private gateway. In such cases, a NAT service need to be configured on the private gateway to avoid IP conflicts. If Source NAT is enabled, the -guest VMs in VPC reaches the enterprise network via private gateway IP +Guest Instances in VPC reaches the enterprise network via private gateway IP address by using the NAT service. The Source NAT service on a private gateway can be enabled while adding @@ -663,39 +709,39 @@ continue functioning. You cannot add a static route if the route is denied for the zone. -Deploying VMs to the Tier -~~~~~~~~~~~~~~~~~~~~~~~~~ +Deploying Instances to the Tier +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + Instances. The VPC page is displayed where all the tiers you have created are listed. -#. Click Virtual Machines tab of the tier to which you want to add a VM. +#. Click Instances tab of the tier to which you want to add an Instance. |add-vm-vpc.png| The Add Instance page is displayed. - Follow the on-screen instruction to add an instance. For information - on adding an instance, see the Installation Guide. + Follow the on-screen instruction to add an Instance. For information + on adding an Instance, see the Installation Guide. -Deploying VMs to VPC Tier and Shared Networks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Deploying Instances to VPC Tier and Shared Networks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack allows you deploy VMs on a VPC tier and one or more shared -networks. With this feature, VMs deployed in a multi-tier application +CloudStack allows you deploy Instances on a VPC tier and one or more shared +networks. With this feature, Instances deployed in a multi-tier application can receive monitoring services via a shared network provided by a service provider. @@ -707,21 +753,21 @@ service provider. #. Select a zone. -#. Select a template or ISO, then follow the steps in the wizard. +#. Select a Template or ISO, then follow the steps in the wizard. #. Ensure that the hardware you have allows starting the selected service offering. -#. Under Networks, select the desired networks for the VM you are +#. Under Networks, select the desired networks for the Instance you are launching. - You can deploy a VM to a VPC tier and multiple shared networks. + You can deploy an Instance to a VPC tier and multiple shared networks. |addvm-tier-sharednw.png| #. Click Next, review the configuration and click Launch. - Your VM will be deployed to the selected VPC tier and shared network. + Your Instance will be deployed to the selected VPC tier and shared network. Acquiring a New IP Address for a VPC @@ -733,17 +779,17 @@ guest network only when the first port-forwarding, load balancing, or Static NAT rule is created for the IP or the network. IP can't be associated to more than one network at a time. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + Instances. The VPC page is displayed where all the tiers you created are listed in a diagram. @@ -756,7 +802,7 @@ associated to more than one network at a time. - Static NAT - - Virtual Machines + - Instances - CIDR @@ -768,7 +814,7 @@ associated to more than one network at a time. - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select IP Addresses. @@ -782,8 +828,8 @@ associated to more than one network at a time. address in port forwarding, load balancing, and static NAT rules. -Releasing an IP Address Alloted to a VPC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Releasing an IP Address Allotted to a VPC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The IP address is a limited resource. If you no longer need a particular IP, you can disassociate it from its VPC and return it to the pool of @@ -792,13 +838,13 @@ when all the networking ( port forwarding, load balancing, or StaticNAT ) rules are removed for this IP address. The released IP address will still belongs to the same VPC. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC whose IP you want to release. @@ -814,7 +860,7 @@ still belongs to the same VPC. - Static NAT - - Virtual Machines + - Instances - CIDR @@ -826,7 +872,7 @@ still belongs to the same VPC. - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. Select Public IP Addresses. @@ -843,26 +889,26 @@ Enabling or Disabling Static NAT on a VPC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A static NAT rule maps a public IP address to the private IP address of -a VM in a VPC to allow Internet traffic to it. This section tells how to +an Instance in a VPC to allow Internet traffic to it. This section tells how to enable or disable static NAT for a particular IP address in a VPC. If port forwarding rules are already in effect for an IP address, you cannot enable static NAT to that IP. -If a guest VM is part of more than one network, static NAT rules will +If a Guest Instance is part of more than one network, static NAT rules will function only if they are defined on the default network. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation, choose Network. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + Instances. The VPC page is displayed where all the tiers you created are listed in a diagram. @@ -875,7 +921,7 @@ function only if they are defined on the default network. - Static NAT - - Virtual Machines + - Instances - CIDR @@ -887,7 +933,7 @@ function only if they are defined on the default network. - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. In the Router node, select Public IP Addresses. @@ -904,7 +950,7 @@ function only if they are defined on the default network. |select-vmstatic-nat.png| -#. Select the tier and the destination VM, then click Apply. +#. Select the tier and the destination Instance, then click Apply. Adding Load Balancing Rules on a VPC @@ -916,20 +962,20 @@ the traffic received at a public IP of the VPC virtual router. The traffic is load balanced within a tier based on your configuration. Citrix NetScaler and VPC virtual router are supported for external LB. When you use internal LB service, traffic received at a tier is load -balanced across different VMs within that tier. For example, traffic -reached at Web tier is redirected to another VM in that tier. External +balanced across different Instances within that tier. For example, traffic +reached at Web tier is redirected to another Instance in that tier. External load balancing devices are not supported for internal LB. The service is -provided by a internal LB VM configured on the target tier. +provided by a internal LB Instance configured on the target tier. Load Balancing Within a Tier (External LB) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A CloudStack user or administrator may create load balancing rules that -balance traffic received at a public IP to one or more VMs that belong -to a network tier that provides load balancing service in a VPC. A user +balance traffic received at a public IP to one or more Instances that belong +to a Network Tier that provides load balancing service in a VPC. A user creates a rule, specifies an algorithm, and assigns the rule to a set of -VMs within a tier. +Instances within a tier. Enabling NetScaler as the LB Provider on a VPC Tier @@ -963,7 +1009,7 @@ follows: #. Log in to the CloudStack UI as a user or admin. -#. Naviagte to Service Offerings and choose Network Offering. +#. Navigate to Service Offerings and choose Network Offering. #. Click Add Network Offering. @@ -984,7 +1030,7 @@ follows: - **Persistent**: Indicate whether the guest network is persistent or not. The network that you can provision without having to - deploy a VM on it is termed persistent network. + deploy an Instance on it is termed persistent network. - **VPC**: This option indicate whether the guest network is Virtual Private Cloud-enabled. A Virtual Private Cloud (VPC) is a private, @@ -1024,7 +1070,7 @@ Creating an External LB Rule #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC, for which you want to @@ -1041,7 +1087,7 @@ Creating an External LB Rule - Static NAT - - Virtual Machines + - Instances - CIDR @@ -1053,7 +1099,7 @@ Creating an External LB Rule - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. In the Router node, select Public IP Addresses. @@ -1073,7 +1119,7 @@ Creating an External LB Rule - **Public Port**: The port that receives the incoming traffic to be balanced. - - **Private Port**: The port that the VMs will use to receive the + - **Private Port**: The port that the Instances will use to receive the traffic. - **Algorithm**. Choose the load balancing algorithm you want @@ -1090,7 +1136,13 @@ Creating an External LB Rule algorithm for the stickiness policy. See Sticky Session Policies for Load Balancer Rules. - - **Add VMs**: Click Add VMs, then select two or more VMs that will + - **Protocol**: The protocol for the Load Balancer Rule such as tcp, udp, tcp-proxy or ssl. + + - **SSL Certificate**: The SSL certificate assigned to the Load Balancer Rule. + This is visible only when protocol is ssl. see `"Configuring SSL Certificate for Load Balancer + Rules" `_. + + - **Add Instances**: Click Add Instances, then select two or more Instances that will divide the load of incoming traffic, and click Apply. The new load balancing rule appears in the list. You can repeat these @@ -1116,14 +1168,14 @@ How Does Internal LB Work in VPC? In this figure, a public LB rule is created for the public IP 72.52.125.10 with public port 80 and private port 81. The LB rule, created on the VPC virtual router, is applied on the traffic coming from -the Internet to the VMs on the Web tier. On the Application tier two +the Internet to the Instances on the Web tier. On the Application tier two internal load balancing rules are created. An internal LB rule for the -guest IP 10.10.10.4 with load balancer port 23 and instance port 25 is -configured on the VM, InternalLBVM1. Another internal LB rule for the -guest IP 10.10.10.4 with load balancer port 45 and instance port 46 is -configured on the VM, InternalLBVM1. Another internal LB rule for the -guest IP 10.10.10.6, with load balancer port 23 and instance port 25 is -configured on the VM, InternalLBVM2. +guest IP 10.10.10.4 with load balancer port 23 and Instance port 25 is +configured on the Instance, InternalLBVM1. Another internal LB rule for the +guest IP 10.10.10.4 with load balancer port 45 and Instance port 46 is +configured on the Instance, InternalLBVM1. Another internal LB rule for the +guest IP 10.10.10.6, with load balancer port 23 and Instance port 25 is +configured on the Instance, InternalLBVM2. |vpc-lb.png| @@ -1137,7 +1189,7 @@ Guidelines - Internal LB is supported just on VPC networks in CloudStack 4.2 release. -- Only Internal LB VM can act as the Internal LB provider in CloudStack +- Only Internal LB Instance can act as the Internal LB provider in CloudStack 4.2 release. - Network upgrade is not supported from the network offering with @@ -1169,7 +1221,7 @@ network offering as follows: #. Log in to the CloudStack UI as a user or admin. -#. Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses. +#. Navigate to Service Offerings and choose Network OfferingPublic IP Addresses. #. Click Add Network Offering. @@ -1190,7 +1242,7 @@ network offering as follows: - **Persistent**: Indicate whether the guest network is persistent or not. The network that you can provision without having to - deploy a VM on it is termed persistent network. + deploy an Instance on it is termed persistent network. - **VPC**: This option indicate whether the guest network is Virtual Private Cloud-enabled. A Virtual Private Cloud (VPC) is a private, @@ -1222,13 +1274,13 @@ network offering as follows: Creating an Internal LB Rule '''''''''''''''''''''''''''' -When you create the Internal LB rule and applies to a VM, an Internal LB -VM, which is responsible for load balancing, is created. +When you create the Internal LB rule and applies to an Instance, an Internal LB +Instance, which is responsible for load balancing, is created. -You can view the created Internal LB VM in the Instances page if you +You can view the created Internal LB Instance in the Instances page if you navigate to **Infrastructure** > **Zones** > > > **Network Service Providers** > **Internal -LB VM**. You can manage the Internal LB VMs as and when required from +LB Instance**. You can manage the Internal LB Instances as and when required from the location. #. Log in to the CloudStack UI as an administrator or end user. @@ -1237,7 +1289,7 @@ the location. #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Locate the VPC for which you want to configure internal LB, then @@ -1264,13 +1316,13 @@ the location. specified, the IP address is automatically allocated from the network CIDR. - For every Source IP, a new Internal LB VM is created for load + For every Source IP, a new Internal LB Instance is created for load balancing. - **Source Port**: The port associated with the source IP. Traffic on this port is load balanced. - - **Instance Port**: The port of the internal LB VM. + - **Instance Port**: The port of the internal LB Instance. - **Algorithm**. Choose the load balancing algorithm you want CloudStack to use. CloudStack supports the following well-known @@ -1292,11 +1344,11 @@ Adding a Port Forwarding Rule on a VPC #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Click the Configure button of the VPC to which you want to deploy the - VMs. + Instances. The VPC page is displayed where all the tiers you created are listed in a diagram. @@ -1309,7 +1361,7 @@ Adding a Port Forwarding Rule on a VPC - Static NAT - - Virtual Machines + - Instances - CIDR @@ -1321,7 +1373,7 @@ Adding a Port Forwarding Rule on a VPC - Site-to-Site VPNs - - Network ACL Lists + - Network ACLs #. In the Router node, select Public IP Addresses. @@ -1339,7 +1391,7 @@ Adding a Port Forwarding Rule on a VPC - **Public Port**: The port to which public traffic will be addressed on the IP address you acquired in the previous step. - - **Private Port**: The port on which the instance is listening for + - **Private Port**: The port on which the Instance is listening for forwarded public traffic. - **Protocol**: The communication protocol in use between the two @@ -1349,10 +1401,10 @@ Adding a Port Forwarding Rule on a VPC - UDP - - **Add VM**: Click Add VM. Select the name of the instance to which + - **Add Instance**: Click Add Instance. Select the name of the Instance to which this rule applies, and click Apply. - You can test the rule by opening an SSH session to the instance. + You can test the rule by opening an SSH session to the Instance. Removing Tiers @@ -1370,7 +1422,7 @@ belonging to the same VPC. #. In the Select view, select VPC. - All the VPC that you have created for the account is listed in the + All the VPC that you have created for the Account is listed in the page. #. Click the Configure button of the VPC for which you want to set up @@ -1398,7 +1450,7 @@ Editing, Restarting, and Removing a Virtual Private Cloud #. In the Select view, select VPC. - All the VPCs that you have created for the account is listed in the + All the VPCs that you have created for the Account is listed in the page. #. Select the VPC you want to work with. @@ -1415,18 +1467,38 @@ Editing, Restarting, and Removing a Virtual Private Cloud |restart-vpc.png| +Working with Domain VPCs +~~~~~~~~~~~~~~~~~~~~~~~~ + +The functionality of domain VPCs allows operators to aggregate multiple +Network Tiers from distinct users on the same VPC, reducing the number of virtual +routers necessary in the environment, and consequently, decreasing the +amount of public IP addresses consumed. All Network Tiers added to the VPC share +the same VR, but each one has their own broadcast domain and features +implemented by the VPC, such as DHCP, NAT, and so on. + +In order to utilize this functionality, a new Network Tier must be included to an +existing VPC by inputing the respective data for the account and the VPC +on the **'createNetwork'** API. It is important to note that, in order +for a Network Tier of a different account to be created on the VPC, the account +that creates the Network Tier must have access to both the account that owns the +VPC and the account that owns the Network Tier. The owner of the VPC must also +have access to the account that owns the Network Tier, however, the opposite +is not required. + + .. |add-vpc.png| image:: /_static/images/add-vpc.png :alt: adding a vpc. .. |add-tier.png| image:: /_static/images/add-tier.png :alt: adding a tier to a vpc. .. |replace-acl-icon.png| image:: /_static/images/replace-acl-icon.png - :alt: button to replace an ACL list -.. |add-new-gateway-vpc.png| image:: /_static/images/add-new-gateway-vpc.png + :alt: button to replace an ACL +.. |add-new-gateway-vpc2.png| image:: /_static/images/add-new-gateway-vpc2.png :alt: adding a private gateway for the VPC. .. |add-vm-vpc.png| image:: /_static/images/add-vm-vpc.png - :alt: adding a VM to a vpc. + :alt: adding an Instance to a VPC. .. |addvm-tier-sharednw.png| image:: /_static/images/addvm-tier-sharednw.png - :alt: adding a VM to a VPC tier and shared network. + :alt: adding an Instance to a VPC tier and shared network. .. |release-ip-icon.png| image:: /_static/images/release-ip-icon.png :alt: button to release an IP. .. |enable-disable.png| image:: /_static/images/enable-disable.png diff --git a/source/adminguide/networking/vnf_templates_appliances.rst b/source/adminguide/networking/vnf_templates_appliances.rst new file mode 100644 index 0000000000..2ba354586a --- /dev/null +++ b/source/adminguide/networking/vnf_templates_appliances.rst @@ -0,0 +1,181 @@ +.. 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. + + +VNF Templates and Appliances +============================ + +Virtualized Network Functions (VNFs) refers to virtualized software applications +which offers network services, for example routers, firewalls, load balancers. + + +Adding a VNF template from an URL +----------------------------------------------------------- + +To create a VNF appliance, user needs to register a VNF template and add VNF settings. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Images -> Templates + +#. Click on the "Register template from URL" button. + +#. Specify the "Template type" to "VNF" + +#. Click on the OK button. + +When the VNF template is registered successfully, you will see the template on +the same page or under Network -> VNF templates. + + For more information, see `“Uploading Templates from a remote HTTP server” + <../templates.html#uploading-templates-from-a-remote-http-server>`_. + + +Updating a VM template to VNF template +----------------------------------------------------------- + +Users are able to update an existing VM template, which is uploaded from +HTTP server or local, or created from volume, to be a VNF template. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Images -> Templates + +#. Select the VM template you want to work with. + +#. Go into System Preferences -> Network + +#. Change the "Template type" to "VNF" + +#. Click on the OK button. + + +Updating the VNF settings of a VNF template +----------------------------------------------------------- + +Users need to add the VNF nics and VNF details of the VNF templates. + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Images -> Templates + +#. Select the VNF template you want to work with. + +#. Click on the "VNF settings" tab of the VNF template + + |vnf-template-vnf-settings.png| + +#. To add VNF nics, click on the "Add VNF nic" button + + |vnf-add-nic.png| + + The following parameters are supported. + + - deviceid: The device ID of the VNF nic. The device id must be consecutive and start from 0. + + - name: The name of the VNF nic. + + - required: True if the VNF nic is required. Otherwise it is optional. It cannot be true if a preceding nic is optional. + + - management: True if the VNF nic is a management interface. False otherwise + + - description: The description of the VNF nic. + + When VNF nics are added, users will see the list of VNF nics. + + |vnf-nics-list.png| + +#. To add VNF details, click on the "Add VNF detail" button + + |vnf-add-detail.png| + + The following parameters are supported. + + - name: The name of the VNF detail. The valid values are: ACCESS_METHODS, + USERNAME, PASSWORD, SSH_USER, SSH_PASSWORD, SSH_PORT, WEB_USER, WEB_PASSWORD, + HTTP_PATH, HTTP_PORT, HTTPS_PATH, HTTPS_PORT, ICON, VERSION, VENDOR and MAINTAINER + + - value: The value of the VNF detail. If the name is access_methods, the valid values are: console, http, https, ssh-key, ssh-password + +#. To edit or remove VNF details, click on the corresponding icon of each VNF detail. + + |vnf-details-list.png| + + +Deploying VNF appliances +----------------------------------------------------------- + +#. Log in to the CloudStack UI as an administrator or end user. + +#. In the left navigation, choose Network -> VNF appliances + +#. Click on the "Add VNF Appliance" button. + + For more information, see `“Creating VMs” + <../virtual_machines.html#creating-vms>`_. + +#. Choose the networks you want to add to the VNF appliance + + |vnf-appliance-networks-selection.png| + +#. In the "VNF nics" step, choose the network each VNF nic will use + + |vnf-appliance-vnf-nics.png| + + The following parameters are supported, if the management network is an Isolated + network or Shared network with security groups. + + - Configure rules for VNF management interfaces. False by default. + + - Source cidr list of rules. It is The CIDR list to forward traffic from to the + VNF management interface. Multiple entries must be separated by a single comma + character (,). The default value is 0.0.0.0/0. + + .. note:: + The following network rules will be applied. + + - If management network is an isolated network, CloudStack will acquire a public + IP, enable static nat on the VNF appliance, and create firewall rules to allow + traffic to ssh/http/https ports based on access_methods in VNF template details. + + - If management network is a shared network with security groups, CloudStack will + create a new security group with rules to allow traffic to ssh/http/https ports + based on access_methods in VNF template details, and assign to the VNF appliance. + + - If management network is a L2 network, VPC tier or Shared network without security + groups, no network rules will be configured. + + +#. Click on the "Launch VNF appliance" button + +When the VNF appliance is deployed successfully, you will see the VNF appliance on +the "VNF appliances" page. + + +.. |vnf-template-vnf-settings.png| image:: /_static/images/vnf-template-vnf-settings.png + :alt: VNF settings of VM template +.. |vnf-add-nic.png| image:: /_static/images/vnf-add-nic.png + :alt: Add VNF nic +.. |vnf-nics-list.png| image:: /_static/images/vnf-nics-list.png + :alt: List of VNF nics +.. |vnf-add-detail.png| image:: /_static/images/vnf-add-detail.png + :alt: Add VNF detail +.. |vnf-details-list.png| image:: /_static/images/vnf-details-list.png + :alt: List of VNF details +.. |vnf-appliance-networks-selection.png| image:: /_static/images/vnf-appliance-networks-selection.png + :alt: Select networks for VNF appliance +.. |vnf-appliance-vnf-nics.png| image:: /_static/images/vnf-appliance-vnf-nics.png + :alt: Specify VNF nics of VNF appliance + diff --git a/source/adminguide/networking_and_traffic.rst b/source/adminguide/networking_and_traffic.rst index c0fbe69f03..b02d774182 100644 --- a/source/adminguide/networking_and_traffic.rst +++ b/source/adminguide/networking_and_traffic.rst @@ -14,7 +14,7 @@ under the License. -In a CloudStack, guest VMs can communicate with each other using shared +In a CloudStack, Guest Instances can communicate with each other using shared infrastructure with the security and user perception that the guests have a private LAN. The CloudStack virtual router is the main component providing networking features for guest traffic. @@ -29,8 +29,14 @@ providing networking features for guest traffic. .. include:: networking/advanced_zone_config.rst +.. include:: networking/manage_guest_networks.rst + .. include:: networking/multiple_guest_networks.rst +.. include:: networking/dynamic_static_routing.rst + +.. include:: networking/network_permissions.rst + .. include:: networking/ip_reservation_in_guest_networks.rst .. include:: networking/public_ips_and_vlans_for_accounts.rst @@ -59,6 +65,8 @@ providing networking features for guest traffic. .. include:: networking/releasing_an_ip_address.rst +.. include:: networking/reserving_an_ip_address.rst + .. include:: networking/static_nat.rst .. include:: networking/ip_forwarding_and_firewalling.rst diff --git a/source/adminguide/projects.rst b/source/adminguide/projects.rst index 68ceec0026..c497adbf6b 100644 --- a/source/adminguide/projects.rst +++ b/source/adminguide/projects.rst @@ -17,71 +17,71 @@ Overview of Projects -------------------- -Projects are used to organize people and resources. CloudStack users +Projects are used to organize people and resources. CloudStack Users within a single domain can group themselves into project teams so they -can collaborate and share virtual resources such as VMs, snapshots, -templates, data disks, and IP addresses. CloudStack tracks resource -usage per project as well as per user, so the usage can be billed to -either a user account or a project. For example, a private cloud within +can collaborate and share virtual resources such as Instances, Snapshots, +Templates, data disks, and IP addresses. CloudStack tracks resource +usage per project as well as per User, so the usage can be billed to +either a User Account or a project. For example, a private cloud within a software company might have all members of the QA department assigned to one project, so the company can track the resources used in testing while the project members can more easily isolate their efforts from -other users of the same cloud +other Users of the same cloud -You can configure CloudStack to allow any user to create a new project, +You can configure CloudStack to allow any User to create a new project, or you can restrict that ability to just CloudStack administrators. Once you have created a project, you become that project’s administrator, and you can add others within your domain to the project. CloudStack can be set up to either add people directly to a project, or to send an invitation which the recipient must accept. Project members can view and manage all virtual resources created by anyone in the project -(for example, share VMs). A user can be a member of any number of projects +(for example, share Instances). A User can be a member of any number of projects and can switch views in the CloudStack UI to show only project-related information, -such as project VMs, fellow project members, project-related alerts, and so on. +such as project Instances, fellow project members, project-related alerts, and so on. From CloudStack 4.15 onwards, it is possible for a project to have -multiple project administrators and to add/invite specific users of -an account to a project in addition to adding accounts. By means of -Project Roles associated with a user or an account of the project, -it is possible to restrict access of users in a project, i.e., in -addition to account-level roles, one can further restrict access to +multiple project administrators and to add/invite specific Users of +an Account to a project in addition to adding Accounts. By means of +Project Roles associated with a User or an Account of the project, +it is possible to restrict access of Users in a project, i.e., in +addition to Account-level roles, one can further restrict access to operations (or APIs) by associating a project-level role to the -user or account. However, if an account has already been added, one will not -be able to associate a role to a specific user of that account. +User or Account. However, if an Account has already been added, one will not +be able to associate a role to a specific User of that Account. -**NOTE:** Project Roles work over Account level Roles. If a user/account is +**NOTE:** Project Roles work over Account level Roles. If a User/Account is added to a project without a project role, it would imply that the -user / account added will have access to all APIs that are made available +User / Account added will have access to all APIs that are made available by the Account level role. If there are no specific deny rules in the -project role, it would again fallback onto the account-level role to decide -whether the user has permissions to perform a specific action. It is also to be +project role, it would again fallback onto the Account-level role to decide +whether the User has permissions to perform a specific action. It is also to be noted that Project roles are restrictive in nature, i.e., to say that, one may -not allow a user to perform an operation that is NOT allowed at the Account level. +not allow a User to perform an operation that is NOT allowed at the Account level. Even if a rule is added at the project level, allowing such an action, it will not have any effect as the action will be prohibited by the Account Role. -The project administrator can promote or demote a user in the project. +The project administrator can promote or demote a User in the project. The project administrator can also add more members, remove members from the project, set new resource limits (as long as they are below the global defaults set by the CloudStack administrator), and delete the project. When the administrator removes a member from the -project, resources created by that user, such as VM instances, remain +project, resources created by that User, such as Instances, remain with the project. This brings us to the subject of resource ownership and which resources can be used by a project. Resources created within a project are owned by the project, not by any -particular CloudStack account, and they can be used only within the -project. A user who belongs to one or more projects can still create +particular CloudStack Account, and they can be used only within the +project. A User who belongs to one or more projects can still create resources outside of those projects, and those resources belong to the -user’s account; they will not be counted against the project’s usage or +User’s Account; they will not be counted against the project’s usage or resource limits. You can create project-level networks to isolate traffic within the project and provide network services such as port forwarding, load balancing, VPN, and static NAT. A project can also make use of certain types of resources from outside the project, if those -resources are shared. For example, a shared network or public template +resources are shared. For example, a shared network or public Template is available to any project in the domain. A project can get access to a -private template if the template’s owner will grant permission. A +private Template if the Template’s owner will grant permission. A project can use any service offering or disk offering available in its domain; however, you can not create private service and disk offerings at the project level. @@ -90,7 +90,7 @@ at the project level. Configuring Projects -------------------- -Before CloudStack users start using projects, the CloudStack +Before CloudStack Users start using projects, the CloudStack administrator must set up various systems to support them, including membership invitations, limits on project resources, and controls on who can create projects. @@ -102,7 +102,7 @@ Setting Up Invitations CloudStack can be set up either so that project administrators can add people directly to a project, or so that it is necessary to send an invitation which the recipient must accept. The invitation can be sent -by email or through the user’s CloudStack account. If you want +by email or through the User’s CloudStack Account. If you want administrators to use invitations to add members to projects, turn on and set up the invitations feature in CloudStack. @@ -152,12 +152,11 @@ Setting Resource Limits for Projects The CloudStack administrator can set global default limits to control the amount of resources that can be owned by each project in the cloud. This serves to prevent uncontrolled usage of resources such as -snapshots, IP addresses, and virtual machine instances. Domain -administrators can override these resource limits for individual -projects with their domains, as long as the new limits are below the -global defaults set by the CloudStack root administrator. The root -administrator can also set lower resource limits for any project in the -cloud +Snapshots, IP addresses, and Instances. Domain administrators can override +these resource limits for individual projects with their domains, +as long as the new limits are below the global defaults set by the CloudStack +root administrator. The root administrator can also set lower resource limits +for any project in the cloud. Setting Per-Project Resource Limits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -206,17 +205,35 @@ Setting the Global Project Resource Limits .. cssclass:: table-striped table-bordered table-hover - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ - | max.project.public.ips | Maximum number of public IP addresses that can be owned by any project in the cloud. See About Public IP Addresses. | - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ - | max.project.snapshots | Maximum number of snapshots that can be owned by any project in the cloud. See Working with Snapshots. | - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ - | max.project.templates | Maximum number of templates that can be owned by any project in the cloud. See Working with Templates. | - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ - | max.project.uservms | Maximum number of guest virtual machines that can be owned by any project in the cloud. See Working With Virtual Machines. | - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ - | max.project.volumes | Maximum number of data volumes that can be owned by any project in the cloud. See Working with Volumes. | - +--------------------------+------------------------------------------------------------------------------------------------------------------------------+ + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.public.ips | Default maximum number of public IP addresses that can be owned by any project in the cloud. See About Public IP Addresses. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.snapshots | Default maximum number of Snapshots that can be owned by any project in the cloud. See Working with Snapshots. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.templates | Default maximum number of Templates that can be owned by any project in the cloud. See Working with Templates. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.uservms | Default maximum number of guest Instances that can be owned by any project in the cloud. See Working With Instances. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.volumes | Default maximum number of data volumes that can be owned by any project in the cloud. See Working with Volumes. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.networks | Default maximum number of networks that can be owned by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.vpcs | Default maximum number of vpcs that can be owned by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.cpus | Default maximum number of cpu cores that can be owned by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.memory | Default maximum memory (in MB) that can be used by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.primary.storage | Default maximum primary storage space (in GiB) that can be used by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.backups | Default maximum number of backups that can be owned by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.backup.storage | Default maximum backup storage (in GiB) that can be used by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.buckets | Default maximum number of buckets that can be owned by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | max.project.object storage | Default maximum Object storage (in GiB) that can be used by any project in the cloud. | + +-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+ #. Restart the Management Server. @@ -228,7 +245,7 @@ Setting the Global Project Resource Limits Setting Project Creator Permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can configure CloudStack to allow any user to create a new project, +You can configure CloudStack to allow any User to create a new project, or you can restrict that ability to just CloudStack administrators. #. Log in as administrator to the CloudStack UI. @@ -241,7 +258,7 @@ or you can restrict that ability to just CloudStack administrators. ``allow.user.create.projects`` - Set to true to allow end users to create projects. Set to false if + Set to true to allow end Users to create projects. Set to false if you want only the CloudStack root administrator and domain administrators to create projects. @@ -257,7 +274,7 @@ Creating a New Project CloudStack administrators and domain administrators can create projects. If the global configuration parameter allow.user.create.projects is set -to true, end users can also create projects. +to true, end Users can also create projects. #. Log in as administrator to the CloudStack UI. @@ -265,7 +282,7 @@ to true, end users can also create projects. #. Click New Project. -#. Give the project a name and description for display to users, then +#. Give the project a name and description for display to Users, then click Create Project. #. A screen appears where you can immediately add more members to the @@ -289,6 +306,17 @@ to add members in CloudStack, but only one way is enabled at a time: the UI. +Working with Project Roles +-------------------------- +CloudStack allows adding project members with a desired project role. A +project role will be assigned to the member in addition to their base +account role. Project Roles are restrictive in nature and can be used to +further restrict certain API access to the members within the project. +It is important to note that a project role cannot be used to elevate an +existing user's permissions. Project roles can be created or managed +using `Project roles` tab in the project details UI. + + Sending Project Membership Invitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -303,13 +331,13 @@ not turned on, use the procedure in Adding Project Members From the UI. #. Click the name of the project you want to work with. -#. Click on the `Add Account to Project` button. This will have 2 tabs, one to add account to the project and the other to add a user to the project. Here, we can specify the: +#. Click on the `Add Account to Project` button. This will have 2 tabs, one to add Account to the project and the other to add a User to the project. Here, we can specify the: - - account or user and/or email id of the user to be invited, - - (Optional) the Role i.e, Admin or Regular that the user is to be added as, defualts to Regular role, - - (Optional) the Project role specifying the list of APIs the user is allowed/ denied access to + - Account or User and/or email id of the User to be invited, + - (Optional) the Role i.e, Admin or Regular that the User is to be added as, defaults to Regular role, + - (Optional) the Project role specifying the list of APIs the User is allowed/ denied access to - You can invite only people who have an account in this cloud within the same domain as the project. However, you can send the invitation to any email address. + You can invite only people who have an Account in this cloud within the same domain as the project. However, you can send the invitation to any email address. #. To view and manage the invitations you have sent, return to this tab. When an invitation is accepted, the new member will appear in the @@ -332,13 +360,13 @@ Invitations” <#sending-project-membership-invitations>`_. #. Click the name of the project you want to work with. -#. Click on the `Add Account to Project` button. This will have 2 tabs, one to add account to the project and the other to add a user to the project. Here, we can specify the: +#. Click on the `Add Account to Project` button. This will have 2 tabs, one to add Account to the project and the other to add a User to the project. Here, we can specify the: - - account or user and/or email id of the user to be invited, - - (Optional) the Role i.e, Admin or Regular that the user is to be added as, defualts to Regular role, - - (Optional) the Project role specifying the list of APIs the user is allowed/ denied access to + - Account or User and/or email id of the User to be invited, + - (Optional) the Role i.e, Admin or Regular that the User is to be added as, defaults to Regular role, + - (Optional) the Project role specifying the list of APIs the User is allowed/ denied access to -#. You can add only people who have an account in this cloud and within the same domain as the project. +#. You can add only people who have an Account in this cloud and within the same domain as the project. Accepting a Membership Invitation @@ -356,7 +384,7 @@ want to accept the invitation, follow these steps: #. If you see the invitation listed onscreen, click the Accept button. Invitations listed on screen were sent to you using your CloudStack - account name. + Account name. #. If you received an email invitation, click the Enter Token button, and provide the project ID and unique ID code (token) from the email. @@ -370,7 +398,7 @@ can no longer be used. No new resources or members can be added to a suspended project. When a project is deleted, its resources are destroyed, and member -accounts are removed from the project. The project’s status is shown as +Accounts are removed from the project. The project’s status is shown as Disabled pending final deletion. A project can be suspended or deleted by the project administrator, the @@ -403,13 +431,13 @@ and resources. #. Click Project View. -#. The project dashboard appears, showing the project’s VMs, volumes, - users, events, network settings, and more. From the dashboard, you +#. The project dashboard appears, showing the project’s Instances, volumes, + Users, events, network settings, and more. From the dashboard, you can: - Click the Accounts tab to view and manage project members. If you are the project administrator, you can add new members, remove - members, or change the role of a member from user to admin or vice versa. + members, or change the role of a member from User to admin or vice versa. - (If invitations are enabled) Click the Invitations button to view and manage invitations that have been sent to new project members but diff --git a/source/adminguide/reliability.rst b/source/adminguide/reliability.rst index 735a81bc8e..ff0bb63a96 100644 --- a/source/adminguide/reliability.rst +++ b/source/adminguide/reliability.rst @@ -23,10 +23,10 @@ failures. The Management Server itself (as distinct from the MySQL database) is stateless and may be placed behind a load balancer. Normal operation of Hosts is not impacted by an outage of all Management -Serves. All guest VMs will continue to work. +Serves. All Guest Instances will continue to work. -When the Management Server is down, no new VMs can be created, and the -end user and admin UI, API, dynamic load distribution, and HA will cease +When the Management Server is down, no new Instances can be created, and the +end User and admin UI, API, dynamic load distribution, and HA will cease to work. .. _management-server-load-balancing: @@ -66,7 +66,7 @@ Multiple Management Servers Support on agents In a Cloudstack environment with multiple management servers, an agent can be configured, based on an algorithm, to which management server to connect to. -This can be useful as an internal loadbalancer or for high availability. +This can be useful as an internal load balancer or for high availability. An administrator is responsible for setting the list of management servers and choosing a sorting algorithm using global settings. The management server is responsible for propagating the settings to the @@ -75,7 +75,7 @@ Virtual Machine, Console Proxy Virtual Machine or the KVM hosts). The three global settings that need to be configured are the following: -- hosts: a comma seperated list of management server IP addresses +- hosts: a comma separated list of management server IP addresses - indirect.agent.lb.algorithm: The algorithm for the indirect agent LB - indirect.agent.lb.check.interval: The preferred host check interval for the agent's background task that checks and switches to an agent's @@ -135,72 +135,84 @@ Setting 'host' = 'A,B,C', agents will receive lists depending on receives: 'B,C,A', third agent receives: 'C,B,A' 'shuffle': Each agent will receive a list in random order. -HA-Enabled Virtual Machines ---------------------------- +HA-Enabled Instances +-------------------- -The user can specify a virtual machine as HA-enabled. By default, all -virtual router VMs and Elastic Load Balancing VMs are automatically -configured as HA-enabled. When an HA-enabled VM crashes, CloudStack -detects the crash and restarts the VM automatically within the same +The User can specify an Instance as HA-enabled. By default, all +virtual router Instances and Elastic Load Balancing Instances are automatically +configured as HA-enabled. When an HA-enabled Instance crashes, CloudStack +detects the crash and restarts the Instance automatically within the same Availability Zone. HA is never performed across different Availability -Zones. CloudStack has a conservative policy towards restarting VMs and -ensures that there will never be two instances of the same VM running at -the same time. The Management Server attempts to start the VM on another +Zones. CloudStack has a conservative policy towards restarting Instances and +ensures that there will never be two equal Instances running at +the same time. The Management Server attempts to start the Instance on another Host in the same cluster. HA features work with iSCSI or NFS primary storage. HA with local storage is not supported. +.. note:: + HA-Enabled Instances will be restarted when it is detected that the Instance is + crashed beyond a shadow of a doubt. When the host it is running on is + unreachable, either because of Network issue or because it is crashed, + CloudStack can not be sure the disk image of the Instance is not still being + accessed and will not restart the Instance. + Dedicated HA Hosts ------------------ -One or more hosts can be designated for use only by HA-enabled VMs that +One or more hosts can be designated for use only by HA-enabled Instances that are restarting due to a host failure. Setting up a pool of such -dedicated HA hosts as the recovery destination for all HA-enabled VMs is +dedicated HA hosts as the recovery destination for all HA-enabled Instances is useful to: -- Make it easier to determine which VMs have been restarted as part of - the CloudStack high-availability function. If a VM is running on a - dedicated HA host, then it must be an HA-enabled VM whose original +- Make it easier to determine which Instances have been restarted as part of + the CloudStack high-availability function. If an Instance is running on a + dedicated HA host, then it must be an HA-enabled Instance whose original host failed. (With one exception: It is possible for an administrator - to manually migrate any VM to a dedicated HA host.). + to manually migrate any Instance to a dedicated HA host.). -- Keep HA-enabled VMs from restarting on hosts which may be reserved +- Keep HA-enabled Instances from restarting on hosts which may be reserved for other purposes. The dedicated HA option is set through a special host tag when the host is created. To allow the administrator to dedicate hosts to only -HA-enabled VMs, set the global configuration variable ha.tag to the +HA-enabled Instances, set the global configuration variable ha.tag to the desired tag (for example, "ha\_host"), and restart the Management Server. Enter the value in the Host Tags field when adding the host(s) -that you want to dedicate to HA-enabled VMs. +that you want to dedicate to HA-enabled Instances. .. note:: If you set ha.tag, be sure to actually use that tag on at least one host in your cloud. If the tag specified in ha.tag is not set for - any host in the cloud, the HA-enabled VMs will fail to restart after + any host in the cloud, the HA-enabled Instances will fail to restart after a crash. HA-Enabled Hosts ---------------- -The user can specify a host as HA-enabled, In the event of a host -failure, attemps will be made to recover the failed host by first +.. note:: + This feature is only applicable to KVM clusters. It is not supported + on for instance VMware or Xen. For those hypervisor types, the Host HA + is left to the VMware-cluster or Xen-pool respectively. + +The User can specify a host as HA-enabled, In the event of a host +failure, attempts will be made to recover the failed host by first issuing some OOBM commands. If the host recovery fails the host will be fenced and placed into maintenance mode. To restore the host to normal operation, manual intervention would then be required. Out of band management is a requirement of HA-Enabled hosts and has to be -confiured on all intended participating hosts. +configured on all intended participating hosts. (see `“Out of band management” `_). Host-HA has granular configuration on a host/cluster/zone level. In a large environment, some hosts from a cluster can be HA-enabled and some not, Host-HA uses a state machine design to manage the operations of recovering -and fencing hosts. The current status of a host is reported when quering a +and fencing hosts. The current status of a host is reported when querying a specific host. Timely health investigations are done on HA-Enabled hosts to monitor for @@ -210,7 +222,7 @@ only when it’s exceeded, will the host transition to a different state. Host-HA uses both health checks and activity checks to make decisions on recovering and fencing actions. Once determined that the host is in faulty state (health checks failed) it runs activity checks to figure out if there is -any disk activity on the VMs running on the specific host. +any disk activity on the Instances running on the specific host. The HA Resource Management Service manages the check/recovery cycle including periodic execution, concurrency management, persistence, back pressure and @@ -236,7 +248,7 @@ states: - SUSPECT - There are health checks failing with the host. - CHECKING - Activity checks are being performed. - DEGRADED - The host is passing the activity check ratio and still providing - service to the end user, but it cannot be managed from the CloudStack + service to the end User, but it cannot be managed from the CloudStack management server. - RECOVERING - The Host-HA framework is trying to recover the host by issuing OOBM jobs. @@ -288,14 +300,14 @@ Primary Storage Outage and Data Loss ------------------------------------ When a primary storage outage occurs the hypervisor immediately stops -all VMs stored on that storage device. Guests that are marked for HA +all Instances stored on that storage device. Guests that are marked for HA will be restarted as soon as practical when the primary storage comes -back on line. With NFS, the hypervisor may allow the virtual machines to +back on line. With NFS, the hypervisor may allow the Instances to continue running depending on the nature of the issue. For example, an -NFS hang will cause the guest VMs to be suspended until storage +NFS hang will cause the Guest Instances to be suspended until storage connectivity is restored.Primary storage is not designed to be backed up. Individual volumes in primary storage can be backed up using -snapshots. +Templates. Secondary Storage Outage and Data Loss @@ -303,13 +315,13 @@ Secondary Storage Outage and Data Loss For a Zone that has only one secondary storage server, a secondary storage outage will have feature level impact to the system but will not -impact running guest VMs. It may become impossible to create a VM with -the selected template for a user. A user may also not be able to save -snapshots or examine/restore saved snapshots. These features will +impact running Guest Instances. It may become impossible to create an Instance +with the selected Template for a User. A User may also not be able to save +Templates or examine/restore saved Templates. These features will automatically be available when the secondary storage comes back online. Secondary storage data loss will impact recently added user data -including templates, snapshots, and ISO images. Secondary storage should +including Templates, Snapshots, and ISO Images. Secondary storage should be backed up periodically. Multiple secondary storage servers can be provisioned within each zone to increase the scalability of the system. diff --git a/source/adminguide/service_offerings.rst b/source/adminguide/service_offerings.rst index 444200cfc1..f8d0eacce3 100644 --- a/source/adminguide/service_offerings.rst +++ b/source/adminguide/service_offerings.rst @@ -19,11 +19,14 @@ .. |edit-icon.png| image:: /_static/images/edit-icon.png :alt: edit offering button +.. |clone-icon.png| image:: /_static/images/clone-icon.png + :alt: clone offering button + In addition to the physical and logical infrastructure of your cloud and the CloudStack software and servers, you also need a layer of user services so that people can actually make use of the cloud. This means not just a user UI, but a set of options and resources that users can choose from, -such as templates for creating virtual machines, disk storage, and more. +such as Templates for creating Instances, disk storage, and more. If you are running a commercial service, you will be keeping track of what services and resources users are consuming and charging them for that usage. Even if you do not charge anything for people to use your @@ -35,9 +38,9 @@ what services they use and how much of them. Service Offerings, Disk Offerings, Network Offerings, and Templates ------------------------------------------------------------------- -A user creating a new instance can make a variety of choices about its +A user creating a new Instance can make a variety of choices about its characteristics and capabilities. CloudStack provides several ways to -present users with choices when creating a new instance: +present users with choices when creating a new Instance: - Service Offerings, defined by the CloudStack administrator, provide a choice of CPU speed, number of CPUs, RAM size, tags on the root disk, @@ -54,8 +57,8 @@ present users with choices when creating a new instance: - Templates, defined by the CloudStack administrator or by any CloudStack user, are the base OS images that the user can choose from when - creating a new instance. For example, CloudStack includes CentOS as a - template. See Working with Templates. + creating a new Instance. For example, CloudStack includes CentOS as a + Template. See Working with Templates. In addition to these choices that are provided for users, there is another type of service offering which is available only to the CloudStack @@ -91,16 +94,16 @@ Compute and Disk Service Offerings A service offering is a set of virtual hardware features such as CPU core count and speed, memory, and disk size. The CloudStack administrator can set up various offerings, and then end users choose from the -available offerings when they create a new VM. Based on the user’s +available offerings when they create a new Instance. Based on the user’s selected offering, CloudStack emits usage records that can be integrated with billing systems. Compute offerings may be "fixed", "custom constrained" or "custom unconstrained". -In fixed offering the Number of CPUs, Memory and CPU frequecy in each service +In fixed offering the Number of CPUs, Memory and CPU frequency in each service offerings are predefined by the CloudStack administrator, in custom unconstrained offerings they are left undefined so that the end-user can enter their own desired -values when creating a guest instance. Since 4.13 custom constrained offerings have +values when creating a Guest Instance. Since 4.13 custom constrained offerings have been introduced to allow the end-user to enter the number of CPUs and memory required within constraints set by the administrator. The constraints can be different for different custom constrained offerings. This is useful to reduce @@ -108,7 +111,7 @@ the number of offerings the CloudStack administrator has to define; Instead of defining a compute offering for every imaginable combination of values that a user might want, the administrator can define offerings that provide some flexibility to the users and can serve as the basis for several -different VM configurations. +different Instance configurations. A service offering includes the following elements: @@ -121,7 +124,7 @@ A service offering includes the following elements: - How often the charges are generated For example, one service offering might allow users to create a virtual -machine instance that is equivalent to a 1 GHz Intel® Core™ 2 CPU, with +machine Instance that is equivalent to a 1 GHz Intel® Core™ 2 CPU, with 1 GB memory at $0.20/hour, with network traffic metered at $0.10/GB. CloudStack separates service offerings into compute offerings and disk @@ -149,16 +152,36 @@ The disk offering specifies: To support the custom offerings, usage events register events for dynamically -assigned resources. Usage events are registered when a VM is created +assigned resources. Usage events are registered when an Instance is created from a custom compute offering, and upon changing -the compute offering of a stopped or running VM. The values of the +the compute offering of a stopped or running Instance. The values of the parameters, such as CPU, speed, RAM are recorded. Creating a New Compute Offering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. image:: /_static/images/compute_offering_dialog.png +Along with the compute details of the Instance, root volume definition is also +included in the compute offering. The root volume specifications can be included +in the computer offering in two ways. One is disk specifications like disk size, +storage type, tags can be included directly in the compute offering. The other way +is linking a disk offering in the compute offering. The linked disk offering will +be used for the root disk while creating the Instance. Users can also choose a different +disk offering for the root volume while creating the Instance. + +Following are the two ways of creating the compute offering. + +1. Create compute only offering + +.. image:: /_static/images/compute_offering_dailog_with_compute_only_disk_offering.png + :width: 400px + :align: center + :alt: Compute offering dialog box + + +2. Create compute offering associated to a disk offering + +.. image:: /_static/images/compute_offering_dailog_with_diskoffering.png :width: 400px :align: center :alt: Compute offering dialog box @@ -182,23 +205,8 @@ To create a new compute offering: - **Description**: A short description of the offering that can be displayed to users - - **Storage type**: The type of disk that should be allocated. Local - allocates from storage attached directly to the host where the - system VM is running. Shared allocates from storage accessible via - NFS. - - - **Provisioning type**: The type of disk that should be allocated. - Valid values are thin, sparse, fat. When using the VMWare hypervisor, - these values are mapped to the following vSphere disk provisioning types: - - - **thin**: **Thin Provision** - - **sparse**: **Thick Provision Lazy Zeroed** - - **fat**: **Thick Provision Eager Zeroed** - - The disk provisioning type strictness on VMWare is controlled with the zone level setting - **disk.provisioning.type.strictness**. If set to true, the disk is created only when there is a suitable storage pool that supports the disk provisioning type specified by the service/disk offering. If set to false, the disk is created with a disk provisioning type supported by the pool. Default value is false and this is currently supported for VMware only. - - **Compute Offering Type**: The amount of freedom that the end user - has to customise the compute power that their instance has when using this + has to customise the compute power that their Instance has when using this compute offering. The options are; Fixed offering - user has no ability to customise, Custom constrained - user has some latitude to customise the compute within parameters set by the offering, @@ -207,103 +215,62 @@ To create a new compute offering: it enables the admin to set some boundaries. - **# of CPU cores**: The number of cores which should be allocated - to a system VM with this offering. If 'Custom constrained' is checked, the admin will + to the VM with this offering. If 'Custom constrained' is checked, the admin will be asked to enter the minimum and maximum number of CPUs that a user - can request. If 'Custom unconstrained' is checked, this - field does not appear as the user will be prompted to enter a value when creating their guest instance. + can request. If 'Custom unconstrained' is checked, this field does not appear + as the user will be prompted to enter a value when creating their guest Instance. - - **CPU (in MHz)**: The CPU speed of the cores that the guest instance is + - **CPU (in MHz)**: The CPU speed of the cores that the guest Instance is allocated. For example, “2000” would provide a 2GHz CPU clock speed. **This setting only used if CPU cap is selected.** - This value is also passed to the hypervisor as a share value to give VMs + This value is also passed to the hypervisor as a share value to give Instances relative priority when a hypervisor host is over-provisioned. If 'Custom unconstrained' is checked this field does not appear as the user - will be prompted to enter a value when creating their guest instance. + will be prompted to enter a value when creating their guest Instance. - **Memory (in MB)**: The amount of memory in megabytes that the - system VM should be allocated. For example, “2048” would provide + VM should be allocated. For example, “2048” would provide a 2 GB RAM allocation. If 'Custom constrained' is selected, the admin will be asked to enter the minimum and maximum amount of RAM that a user can request. If 'Custom unconstrained' is selected, this field does - not appear as the user will be prompted to enter a value when creating their guest instance. - - - **Network Rate**: Allowed data transfer rate in MB per second. + not appear as the user will be prompted to enter a value when creating their guest Instance. - - **Disk Read Rate** [1]_: Allowed disk read rate in bits per second. - - - **Disk Write Rate** [1]_: Allowed disk write rate in bits per second. - - - **Disk Read Rate** [1]_: Allowed disk read rate in IOPS (input/output - operations per second). + - **Host Tags**: (Optional) Any tags that you use to organize your + hosts - - **Disk Write Rate** [1]_: Allowed disk write rate in IOPS (input/output - operations per second). + - **Network Rate**: Allowed data transfer rate in MB per second. - **Offer HA**: If yes, the administrator can choose to have the - system VM be monitored and as highly available as possible. - - - **QoS Type** [1]_: Three options: Empty (no Quality of Service), hypervisor - (rate limiting enforced on the hypervisor side), and storage - (guaranteed minimum and maximum IOPS enforced on the storage - side). If leveraging QoS, make sure that the hypervisor or storage - system supports this feature. - - - **Custom IOPS** [1]_: If checked, the user can set their own IOPS. If not - checked, the root administrator can define values. If the root - admin does not set values when using storage QoS, default values - are used (the defauls can be overridden if the proper parameters - are passed into CloudStack when creating the primary storage in - question). - - - **Min IOPS** [1]_: Appears only if storage QoS is to be used. Set a - guaranteed minimum number of IOPS to be enforced on the storage - side. - - - **Max IOPS** [1]_: Appears only if storage QoS is to be used. Set a maximum - number of IOPS to be enforced on the storage side (the system may - go above this limit in certain circumstances for short intervals). - - - **Hypervisor Snapshot Reserve** [1]_: For managed storage only. This is - a value that is a percentage of the size of the root disk. For example: - if the root disk is 20 GB and Hypervisor Snapshot Reserve is 200%, the - storage volume that backs the storage repository (XenServer) or - datastore (VMware) in question is sized at 60 GB (20 GB + (20 GB * 2)). - This enables space for hypervisor snapshots in addition to the virtual - disk that represents the root disk. This does not apply for KVM. + VM be monitored and as highly available as possible. - - **Storage Tags**: The tags that should be associated with the - primary storage used by the system VM. + .. note:: + The HA is offered when the VM High Availability manager is enabled in the zone using the setting 'vm.ha.enabled', by default this setting is enabled. + When disabled, alerts are sent during HA attempts when 'vm.ha.alerts.enabled' setting is enabled. - - **Host Tags**: (Optional) Any tags that you use to organize your - hosts + - **Dynamic Scaling Enabled**: If yes, Instance can be dynamically scalable of cpu or memory - **CPU cap**: Whether to limit the level of CPU usage even if spare capacity is available. - - **Public**: Indicate whether the compute offering should be - available to all domains or only some domains. Choose Yes to make it - available to all domains. Choose No to limit the scope to one or more - specific domains. - - - **Volatile**: If checked, VMs created from this service offering + - **Volatile**: If checked, Instances created from this service offering will have their root disks reset upon reboot. This is useful for secure environments that need a fresh start on every boot and for desktops that should not retain state. - **Deployment Planner**: Choose the technique that you would like - CloudStack to use when deploying VMs based on this service + CloudStack to use when deploying Instances based on this service offering. - - **First Fit**: places new VMs on the first host that is found having - sufficient capacity to support the VM's requirements. + - **First Fit**: places new Instances on the first host that is found having + sufficient capacity to support the Instance's requirements. - - **User Dispersing**: makes the best effort to evenly distribute VMs + - **User Dispersing**: makes the best effort to evenly distribute Instances belonging to the same account on different clusters or pods. - - **User Concentrated**: prefers to deploy VMs belonging to the same + - **User Concentrated**: prefers to deploy Instances belonging to the same account within a single pod. - - **Implicit Dedication**: will deploy VMs on private infrastructure that + - **Implicit Dedication**: will deploy instances on private infrastructure that is dedicated to a specific domain or account. If you choose this planner, then you must also pick a value for Planner Mode. See `Dedicating Resources to Accounts and Domains `_. @@ -312,7 +279,7 @@ To create a new compute offering: Installation in the Installation Guide. - **Planner Mode**: Used when ImplicitDedicationPlanner is selected - in the previous field. The planner mode determines how VMs will be + in the previous field. The planner mode determines how instances will be deployed on private infrastructure that is dedicated to a single domain or account. @@ -322,25 +289,34 @@ To create a new compute offering: be shared between different accounts without violating the desktop software's terms of license. - - Preferred: The VM will be deployed in dedicated infrastructure if - possible. Otherwise, the VM can be deployed in shared infrastructure. + - Preferred: The instance will be deployed in dedicated infrastructure if + possible. Otherwise, the instance can be deployed in shared infrastructure. - - **GPU**: Assign a physical GPU(GPU-passthrough) or a portion of a physical - GPU card (vGPU) to the guest VM. It allows graphical applications to run on the VM. + - **GPU Card**: Assign a physical GPU(GPU-passthrough) or a portion of a physical + GPU card (vGPU) to the guest instance. It allows graphical applications to run on the instance. Select the card from the supported list of cards. - The options given are NVIDIA GRID K1 and NVIDIA GRID K2. These are vGPU - capable cards that allow multiple vGPUs on a single physical GPU. If you - want to use a card other than these, follow the instructions in the - **"GPU and vGPU support for CloudStack Guest VMs"** page in the - Cloudstack Version 4.4 Design Docs found in the Cloudstack Wiki. - - - **vGPU Type**: Represents the type of virtual GPU to be assigned to a - guest VM. In this case, only a portion of a physical GPU card (vGPU) is - assigned to the guest VM. - Additionally, the **passthrough vGPU** type is defined to represent a physical GPU - device. A **passthrough vGPU** can directly be assigned to a single guest VM. - In this case, a physical GPU device is exclusively allotted to a single - guest VM. + + - **GPU Profile**: Represents the type of virtual GPU to be assigned to a + guest instance. In this case, only a portion of a physical GPU card (vGPU) is + assigned to the guest instance. + Additionally, the **passthrough** type is defined to represent a physical GPU + device. A **passthrough** can directly be assigned to a single guest instance. + In this case, the physical GPU devices are exclusively allotted to a single guest instance. + + - **GPU Count**: The number of GPUs to be assigned to the guest instance. + This is applicable only for KVM hypervisor. + + - **GPU Display**: Whether to use the GPU device attached to the guest instance for display. + This is applicable only for KVM hypervisor. Depending on the OS and display configuration, + the user might need to set ``video.hardware`` to ``none`` in the instance's settings to + use CPVM for display. To set the ``video.hardware`` setting, navigate to + the instance's details page in the CloudStack UI, click on the + "Settings" tab, and add/or update the ``video.hardware`` setting to ``none``. + + - **Public**: Indicate whether the compute offering should be + available to all domains or only some domains. Choose Yes to make it + available to all domains. Choose No to limit the scope to one or more + specific domains. - **Domain**: This is only visible When 'Public' is unchecked. When visible, this controls the domains which will be able to use this compute offering. A multi-selection @@ -354,11 +330,122 @@ To create a new compute offering: - **Storage Policy**: Name of the storage policy defined at vCenter, this is applicable only for VMware. When a specific Zone is selected, one of the storage policies can be selected from the list box. + - **Purge Resources**: Whether to cleanup instance and its associated resources from + database upon expunge. When set to true, the database records for the instances with the offering and its + associated resources such as volumes, NICs, etc will be purged immediately once the instance is + expunged. The duration between enpunge and purging of the records can be controlled using + the global configuration - _expunged.resource.purge.job.delay_. + + - **Compute only Disk Offering**: When this flag is enabled, a compute only disk offering + is created with the disk related information provided and then linked to the compute offering. + Compute only disk offering is specific to the newly created compute offering to record the + disk related information. when this flag is disabled, existing disk offering can be selected to + associate with the compute offering or a new disk offering can be created at the same time and + associate with the compute offering + + When the flag is enabled + + - **Storage type**: The type of disk that should be allocated. Local + allocates from storage attached directly to the host where the + VM is running. Shared allocates from storage accessible via + NFS. + + - **Provisioning type**: The type of disk that should be allocated. + Valid values are thin, sparse, fat. When using the VMWare hypervisor, + these values are mapped to the following vSphere disk provisioning types: + + - **thin**: **Thin Provision** + - **sparse**: **Thick Provision Lazy Zeroed** + - **fat**: **Thick Provision Eager Zeroed** + + The disk provisioning type strictness on VMWare is controlled with the zone level setting - **disk.provisioning.type.strictness**. If set to true, the disk is created only when there is a suitable storage pool that supports the disk provisioning type specified by the service/disk offering. If set to false, the disk is created with a disk provisioning type supported by the pool. Default value is false and this is currently supported for VMware only. + + - **QoS Type** [1]_: Three options: Empty (no Quality of Service), hypervisor + (rate limiting enforced on the hypervisor side), and storage + (guaranteed minimum and maximum IOPS enforced on the storage + side). If leveraging QoS, make sure that the hypervisor or storage + system supports this feature. + + - **Disk Read Rate** [1]_: Allowed disk read rate in bits per second. + + - **Disk Write Rate** [1]_: Allowed disk write rate in bits per second. + + - **Disk Read Rate** [1]_: Allowed disk read rate in IOPS (input/output + operations per second). + + - **Disk Write Rate** [1]_: Allowed disk write rate in IOPS (input/output + operations per second). + + - **Custom IOPS** [1]_: If checked, the user can set their own IOPS. If not + checked, the root administrator can define values. If the root + admin does not set values when using storage QoS, default values + are used (the defaults can be overridden if the proper parameters + are passed into CloudStack when creating the primary storage in + question). + + - **Min IOPS** [1]_: Appears only if storage QoS is to be used. Set a + guaranteed minimum number of IOPS to be enforced on the storage + side. + + - **Max IOPS** [1]_: Appears only if storage QoS is to be used. Set a maximum + number of IOPS to be enforced on the storage side (the system may + go above this limit in certain circumstances for short intervals). + + - **Hypervisor Snapshot Reserve** [1]_: For managed storage only. This is + a value that is a percentage of the size of the root disk. For example: + if the root disk is 20 GB and Hypervisor Snapshot Reserve is 200%, the + storage volume that backs the storage repository (XenServer) or + datastore (VMware) in question is sized at 60 GB (20 GB + (20 GB * 2)). + This enables space for hypervisor Snapshots in addition to the virtual + disk that represents the root disk. This does not apply for KVM. + + - **Storage Tags**: The tags that should be associated with the + primary storage used by the VM. + + When the flag is disabled + + - **Add Disk Offering**: Create a new disk offering while creating the compute offering itself. + Once disk offering is created, the new disk offering is auto selected from the below Disk Offerings list. + + - **Disk Offerings**: Select one disk offering from the list with which compute offering will be associated + + - **Disk Offering Strictness**: This flag defines the strictness of the disk offering association + with the compute offering. When set to true, overriding of disk offering is not allowed on deploy instance + and change disk offering is not allowed for the ROOT disk + + - **Enable Lease**: When this flag is enabled, Compute Offering is created with 'Instance Lease' enabled. + In CloudStack, a lease for an instance sets a specific time duration (in days) after which a chosen lease action, such as stopping or destroying the instance, will take place. + These lease settings are defined in the Compute Offering and are automatically applied to any Instance created using it. + + .. note:: The global configuration ``instance.lease.enabled`` should be configured as true to create compute offering with lease. + + .. note:: Lease duration or expiryaction can't be updated for compute offering. + + ``instance.lease.enabled``: Indicates whether Instance Lease feature is enabled or not. Default is **false** + For more information, see `“Setting Global Configuration Parameters” + <../installguide/configuration.html#setting-global-configuration-parameters>`_. + + When the flag is enabled + + - **Lease Duration (in days)**: Sets the lease duration. An instance created using this compute offering will inherit the lease duration by default. Supported values are in range 1 <= N <= 36500. + + - **Lease expiry action**: Lease expiry action: Denotes lease expiry action, which gets executed upon lease expiry for instances created using this compute offering. + Supported values for lease expiry action are as follows: + + - STOP + - DESTROY + + .. image:: /_static/images/compute_offering_dailog_with_lease.png + :width: 400px + :align: center + :alt: Compute offering dialog box + + #. Click Add. -.. [1] These options are dependant on the capabilities of the hypervisor or the shared storage system which the VMs are on. +.. [1] These options are dependent on the capabilities of the hypervisor or the shared storage system which the instances are on. If the hypervisor or underlying storage don't support a particular capability in the offering, the setting will have no effect. @@ -376,6 +463,12 @@ To create a new disk offering: #. Click Add Disk Offering. + .. image:: /_static/images/disk_offering_dailog.png + :width: 400px + :align: center + :alt: Disk offering dialog box + + #. In the dialog, make the following choices: - **Name**: Any desired name for the disk offering. @@ -400,6 +493,9 @@ To create a new disk offering: The disk provisioning type strictness on VMWare is controlled with the zone level setting - **disk.provisioning.type.strictness**. If set to true, the disk is created only when there is a suitable storage pool that supports the disk provisioning type specified by the service/disk offering. If set to false, the disk is created with a disk provisioning type supported by the pool. Default value is false and this is currently supported for VMware only. + - **Disk Size Strictness**: The flag defines the size strictness of the volume created from this disk offering. + When flag is true, volume's size cannot be changed. + - **QoS Type** [2]_: Three options: Empty (no Quality of Service), hypervisor (rate limiting enforced on the hypervisor side), and storage (guaranteed minimum and maximum IOPS enforced on the storage @@ -409,7 +505,7 @@ To create a new disk offering: - **Custom IOPS** [2]_: If checked, the user can set their own IOPS. If not checked, the root administrator can define values. If the root admin does not set values when using storage QoS, default values - are used (the defauls can be overridden if the proper parameters + are used (the defaults can be overridden if the proper parameters are passed into CloudStack when creating the primary storage in question). @@ -426,7 +522,7 @@ To create a new disk offering: if the data disk is 20 GB and Hypervisor Snapshot Reserve is 200%, the storage volume that backs the storage repository (XenServer) or datastore (VMware) in question is sized at 60 GB (20 GB + (20 GB * 2)). - This enables space for hypervisor snapshots in addition to the virtual + This enables space for hypervisor Snapshots in addition to the virtual disk that represents the data disk. This does not apply for KVM. - **(Optional)Storage Tags**: The tags that should be associated with @@ -457,7 +553,7 @@ To create a new disk offering: #. Click Add. -.. [2] These options are dependant on the capabilities of the hypervisor or the shared storage system which the VMs are on. +.. [2] These options are dependent on the capabilities of the hypervisor or the shared storage system which the instances are on. If the hypervisor or underlying storage don't support a particular capability in the offering, the setting will have no effect. @@ -473,7 +569,7 @@ click on the update offering access button |update-service-offering-button.png|. A service offering can be deleted. If it is no longer in use, it is deleted immediately and permanently. If the service offering is still in -use, it will remain in the database until all the virtual machines +use, it will remain in the database until all the Instances referencing it have been deleted. After deletion by the administrator, a service offering will not be available to end users that are creating new instances. @@ -484,7 +580,7 @@ System Service Offerings System service offerings provide a choice of CPU speed, number of CPUs, tags, and RAM size, just as other service offerings do. But rather than -being used for virtual machine instances and exposed to users, system +being used for Instance and exposed to users, system service offerings are used to change the default properties of virtual routers, console proxies, and other system VMs. System service offerings are visible only to the CloudStack root administrator. CloudStack @@ -542,6 +638,10 @@ To create a system service offering: - **Offer HA**: If yes, the administrator can choose to have the system VM be monitored and as highly available as possible. + .. note:: + The HA is offered when the VM High Availability manager is enabled in the zone using the setting 'vm.ha.enabled', by default this setting is enabled. + When disabled, alerts are sent during HA attempts when 'vm.ha.alerts.enabled' setting is enabled. + - **Storage Tags**: The tags that should be associated with the primary storage used by the system VM. @@ -558,16 +658,27 @@ To create a system service offering: #. Click Add. +Cloning Offerings +----------------- + +From CloudStack 4.23, you can clone an existing compute, disk, network or VPC, +system and backup offerings to create a new offering. This is useful when you want +to create a new offering with similar settings as an existing offering. +To clone an offering, navigate to the offering's list view or details page and +click on the clone icon |clone-icon.png|. +The dialog box for cloning an offering is similar to the one for creating a new offering, +but with some fields pre-filled with the settings of the existing offering. +You can modify any of the settings as needed before clicking Add to create the new offering. + + Network Throttling ------------------ -Network throttling is the process of controlling the network access and -bandwidth usage based on certain rules. CloudStack controls this +Network throttling is the process of controlling the network bandwidth. CloudStack controls this behaviour of the guest networks in the cloud by using the network rate parameter. This parameter is defined as the default data transfer rate in Mbps (Megabits Per Second) allowed in a guest network. It defines the -upper limits for network utilization. If the current utilization is -below the allowed upper limits, access is granted, else revoked. +upper limits for network bandwidth. You can throttle the network bandwidth either to control the usage above a certain limit for some accounts, or to control network congestion in a @@ -596,24 +707,24 @@ on different types of networks in CloudStack. .. cssclass:: table-striped table-bordered table-hover -=========================================== =============================== -Networks Network Rate Is Taken from -=========================================== =============================== -Guest network of Virtual Router Guest Network Offering -Public network of Virtual Router Guest Network Offering -Storage network of Secondary Storage VM System Network Offering -Management network of Secondary Storage VM System Network Offering -Storage network of Console Proxy VM System Network Offering -Management network of Console Proxy VM System Network Offering -Storage network of Virtual Router System Network Offering -Management network of Virtual Router System Network Offering -Public network of Secondary Storage VM System Network Offering -Public network of Console Proxy VM System Network Offering -Default network of a guest VM Compute Offering -Additional networks of a guest VM Corresponding Network Offerings -=========================================== =============================== - -A guest VM must have a default network, and can also have many +============================================ =============================== +Networks Network Rate Is Taken from +============================================ =============================== +Guest network of Virtual Router Guest Network Offering +Public network of Virtual Router Guest Network Offering +Storage network of Secondary Storage VM System Network Offering +Management network of Secondary Storage VM System Network Offering +Storage network of Console Proxy VM System Network Offering +Management network of Console Proxy VM System Network Offering +Storage network of Virtual Router System Network Offering +Management network of Virtual Router System Network Offering +Public network of Secondary Storage instance System Network Offering +Public network of Console Proxy instance System Network Offering +Default network of a guest instance Compute Offering +Additional networks of a guest instance Corresponding Network Offerings +============================================ =============================== + +A guest instance must have a default network, and can also have many additional networks. Depending on various parameters, such as the host and virtual switch used, you can observe a difference in the network rate in your cloud. For example, on a VMware host the actual network @@ -721,3 +832,53 @@ default system offering used for System VMs. #. Destroy the existing CPVM or SSVM offerings and wait for them to be recreated. The new CPVM or SSVM are configured with the new offering. + + +Changing the Default System Offering for Virtual Routers +--------------------------------------------------- + +As a CloudStack administrator, you can change the default system +offering used for Virtual Routers. + +#. Create a new system service offering + + For more information, see `“Creating a New System Offering” + `_. + +#. (Optional) Create a new network offering with SystemOffering + + For more information, see `“Creating a New Network Offering” + `_. + +#. (Optional) Change account setting + + You can change the default system offering for Virtual Routers of a particular + account by changing the account's setting "router.service.offering" to the uuid + of the system offering. + + For more information, see `“Setting Local Configuration Parameters” + <../installguide/configuration.html#setting-local-configuration-parameters>`_. + +#. (Optional) Change global configuration + + You can change the default system offering for Virtual Routers of all accounts + by changing the global configuration "router.service.offering" to the uuid of the system offering. + + For more information, see `“Setting Global Configuration Parameters” + <../installguide/configuration.html#setting-global-configuration-parameters>`_. + +When you create a network, the virtual routers will use the system offering in their Network Offering. +If it is not set, the virtual routers will use the system offering in the account setting. +If the account setting is not set, the virtual routers will use the system offering set in the global configuration. +If the global configuration is not set, the virtual routers will use the default system offering for virtual +routers ("System Offering For Software Router" or "System Offering For Software Router - Local Storage"). + +You can update an existing network to a new network offering. The new virtual routers will use the +new system offering set in the Network Offering, account setting or global configuration. +For more information, see `“Changing the Network Offering on a Guest Network” +`_. + +You can restart the network with cleanup. The new virtual routers, created after the restart, will use +the new system offering, set in the Network Offering, account setting or global configuration. +For more information, see `“Editing, Restarting, and Removing a Guest Network” +`_. diff --git a/source/adminguide/storage.rst b/source/adminguide/storage.rst index e92d9efc6c..dc3dd7b3e5 100644 --- a/source/adminguide/storage.rst +++ b/source/adminguide/storage.rst @@ -63,10 +63,10 @@ Best Practices for Primary Storage Runtime Behavior of Primary Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Root volumes are created automatically when a virtual machine is -created. Root volumes are deleted when the VM is destroyed. Data volumes -can be created and dynamically attached to VMs. Data volumes are not -deleted when VMs are destroyed. +Root volumes are created automatically when an Instance is +created. Root volumes are deleted when the Instance is destroyed. Data volumes +can be created and dynamically attached to Instances. Data volumes are not +deleted when Instances are destroyed. Administrators should monitor the capacity of primary storage devices and add additional primary storage as needed. See :ref:`add-primary-storage`. @@ -75,11 +75,11 @@ Administrators add primary storage to the system by creating a CloudStack storage pool. Each storage pool is associated with a cluster or a zone. -With regards to data disks, when a user executes a Disk Offering to +With regards to data disks, when a User executes a Disk Offering to create a data disk, the information is initially written to the CloudStack database only. Upon the first request that the data disk be -attached to a VM, CloudStack determines what storage to place the volume -on and space is taken from that storage (either from preallocated +attached to an Instance, CloudStack determines what storage to place the volume +on and space is taken from that storage (either from pre-allocated storage or from a storage system (ex. a SAN), depending on how the primary storage was added to CloudStack). @@ -107,7 +107,7 @@ Storage media \\ hypervisor VMware vSphere Citrix XenServer **PowerFlex/ScaleIO** No No Yes No ============================================== ================ ==================== =========================== ============================ -XenServer uses a clustered LVM system to store VM images on iSCSI and +XenServer uses a clustered LVM system to store Instance images on iSCSI and Fiber Channel volumes and does not support over-provisioning in the hypervisor. The storage server itself, however, can support thin-provisioning. As a result the CloudStack can still support storage @@ -146,6 +146,92 @@ could provision 1 iSCSI LUN initially and then add a second iSCSI LUN when the first approaches capacity. +Using Multiple Local Storages (KVM only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since CloudStack 4.17.0.0, multiple local storages are supported on KVM hosts. The changes have been possible by editing the agent.properties file. +Since CloudStack 4.19.0.0, it's possible to add Local storage pool via UI/API as well. +It's advised that only one or the other method is used, not both. + +Manually adding Local Storage Pool +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to use multiple local storage pools, you need to + +#. Enable Local Storage For User VMs in the zone details (Edit the Zone, tick the "Enable local storage for user VMs") + +#. Create local directories on KVM hosts + +#. Edit /etc/cloudstack/agent/agent.properties + + - Add extra directories to "local.storage.path". + - Add UUID of directories to "local.storage.uuid" (UUID can be generated by `uuidgen`). + "local.storage.uuid" must be present in the agent.properties file and should not be deleted. + + .. parsed-literal:: + + local.storage.uuid=a43943c1-1759-4073-9db1-bc0ea19203aa,f5b1220b-4446-42dc-a872-cffd281f9f8c + local.storage.path=/var/lib/libvirt/images,/var/lib/libvirt/images2 + +#. Restart cloudstack-agent service + + - Storage pools will be automatically created in libvirt by the CloudStack agent + +Adding a Local Storage Pool via UI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When using UI, ensure that the scope of the storage is set to "Host", and +ensure that the protocol is set to "Filesystem". + +|adding-local-pool-via-ui.png| + +Adding a Local Storage Pool via Command Line +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using Cloudmonkey command line. + + .. parsed-literal:: + + cmk create storagepool zoneid=07d64765-3123-4fc2-b947-25d2c36f5bb4 name=test provider=DefaultPrimary podid=0af34b96-e88d-440e-a6bd-c4e8aab4aa4a clusterid=49db6a16-2f6c-4583-9d07-37ccceb248ae url=file://10.9.8.7/var/lib/libvirt/images2 + +Changing the Scope of the Primary Storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Scope of a Primary Storage can be changed from Zone-wide to Cluster-wide +and vice versa when the Primary Storage is in Disabled state. +An action button is displayed in UI for each Primary Storage in Disabled state. + +|change-storage-pool-scope-via-ui.png| + +Scope change from Cluster to Zone will connect the Primary Storage to all Hosts +of the zone running the same hypervisor as set on the storage pool. + +|change-storage-pool-scope-to-zone.png| + +Scope change from Zone to Cluster will disconnect the Primary Storage from all +Hosts that were previously connected to the Primary Storage and are not a part +of the specified Cluster. So, if there are running VMs on such hosts using this +Storage Pool, they cannot be disconnected from the hosts. In this case the Scope +change operation will error out. +The user VMs need to be stopped or migrated and system VMs need to be destroyed +while the primary Storage is disabled, before attempting the operation again. +listAffectedVmsForstorageScopeChange API can be used to get the list of all such VMs. + +This might be a long running operation depending on how many hosts are there +in the zone which need to be connected or disconnected to the storage pool. + +This feature is tested and supported for the following hypervisor and storage +combinations: + +- KVM with NFS + +- KVM with CEPH/RBD + +- VMWare with NFS + +It is possible to use this functionality with other configurations but some +manual intervention might be needed by the Administrator to make it work. + Storage Tags ~~~~~~~~~~~~ @@ -167,6 +253,38 @@ same set of tags on the primary storage for all clusters in a pod. Even if different devices are used to present those tags, the set of exposed tags can be the same. +Storage Access Groups +~~~~~~~~~~~~~~~~~~~~~ + +When a primary storage is added in CloudStack, either at the Zone or Cluster scope, +it gets connected to all the hosts within that scope. Using Storage Access Groups, +this behavior can be controlled by defining groups on both primary storage and hosts, +ensuring connections are established only within those groups. When a Storage Access +Group is set on a primary storage (a text string attribute similar to tag), +and the same group is assigned to a host, the primary storage will connect only to that host. +A Storage Access Group can also be applied at the Cluster, Pod, or Zone level, allowing +all hosts in that entity to inherit the group automatically. + +For example, if there are 50 hosts across 10 clusters, with 5 hosts per cluster, +and a zone-wide primary storage is added, it will connect to all 50 hosts. If the +operator wants to limit the connection to a few hosts in just the first 2 clusters, +Storage Access Groups can be set on the primary storage and those specific hosts — +or directly on the two clusters to achieve the same effect. + +Adding Storage Access Group on a primary storage. + +|adding-storage-access-group-on-primary-storage.png| + +Adding Storage Access Group on a host. Similarly it can be applied Cluster/Pod/Zone. + +|adding-storage-access-group-on-host.png| + +A primary storage with a Storage Access Group will connect only to hosts that have the +same Storage Access Group. A storage pool without a Storage Access Group will connect to all hosts, +including those with or without any Storage Access Group. + +Note: Storage Access Groups are not applicable for local primary storages. Currently this is tested with NFS +and Dell PowerFlex storages. Maintenance Mode for Primary Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -182,6 +300,88 @@ The CloudStack will bring the device back online and attempt to start all guests that were running at the time of the entry into maintenance mode. +Browsing files on a primary storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Files can be listed at a path on a primary storage using `listStoragePoolObjects` +command or via UI under "Browser" tab for a primary storage. Depending +on the hypervisor, files and directories on a primary storage will get +associated with the cloudstack resources like snapshots, volumes, +templates, and ISOs. + +.. image:: /_static/images/primary-storage-file-browser.png + :align: center + :alt: File browser for primary storage + +.. note:: + If files or folders are not associated with a cloudstack resource, it doesn't mean that they are not used by cloudstack. + + +Setting NFS Mount Options on the Storage Pool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +NFS mount options can be added while creating an NFS storage pool for +KVM hosts. When the storage pool is mounted on the KVM hypervisor host, +these options will be used. Options currently tested and supported are +`vers` and `nconnect`. + +Although it depends on the NFS server, but commonly supported `vers` values +are `3` for NFSv3 and minor versions `4.0, 4.1 and 4.2` for NFSv4. +`nconnect` values can range from 1 to 16. + +Administrator can give the NFS mount options while adding a Primary Storage +from the Create Zone Wizard as well as the Add Primary Storage form. +|nfs-mount-options-create-zone-wizard.png| +|nfs-mount-options-add-primary-storage.png| + +NFS mount options can be changed on a pre-existing Storage Pool in maintenance +mode using the Edit Primary Storage form. Running VMs using volumes in the +Storage Pool will either be stopped or the volumes would be migrated to other +available pools upon enabling maintenance mode. +Storage Pool will be unmounted and mounted again on the KVM hosts using the +new options upon cancelling the maintenance mode. +|nfs-mount-options-edit-primary-storage.png| + +Mount failing due to an incorrect mount option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Add Storage Pool will fail with the error ``An incorrect mount option was specified``. + +In the Update storage pool case, cancel maintenance will throw the above error. +The Administrator should set the correct mount option and cancel the maintenance mode again. + + +Version Requirements +^^^^^^^^^^^^^^^^^^^^ +This feature needs libvirt version 5.1.0 and above on the KVM hosts. + +The `nconnect` mount option exists in all Linux distributions with kernel 5.3 or higher + +A note on the `nconnect` option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This option defines the count of TCP connections that the client makes +to the NFS server. The `nconnect` setting is applied only during the +first mount process to the particular NFS server for a given NFS version. + +If the same client executes the mount command again to the same NFS server using +the same version, it will get the same `nconnect` value as the first mount. +All mount point to the same server at a given version share the same number +of TCP connections. To change the `nconnect` settings all the such mount points +need to be unmounted and then mounted again with the new `nconnect` value. + +So, from CloudStack’s perspective also, the first storage pool created from an +NFS server will set the `nconnect` setting on the hypervisor host corresponding +to the server. Specifying a different `nconnect` mount option while creating a +new storage pool from the same server will not change the `nconnect` setting on the host. + +Similarly if there is only one pre-existing storage pool from a give NFS server +mounted on the host, modifying the `nconnect` mount option via CloudStack will +change the `nconnect` setting on that host. If there are more than one storage pools +from the same server mounted on a host. Changing the `nconnect` mount option on one +of the storage pools via CloudStack will not do anything. To change the `nconnect` +setting on the host, after modifying `nconnect` mount option on all storage pools, +the host needs to be restarted. + Secondary Storage ----------------- @@ -190,8 +390,27 @@ This section gives concepts and technical details about CloudStack secondary storage. For information about how to install and configure secondary storage through the CloudStack UI, see :ref:`add-secondary-storage`. -Migration of data between secondary storages is now supported. One may choose -to completely migrate the data or migrate data such that the stores +Browsing files on a secondary storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Files can be listed at a path on a secondary storage using `listImageStoreObjects` +command or via UI under "Browser" tab for a secondary storage. Depending +on the hypervisor, files and directories on a primary storage will get +associated with the cloudstack resources like snapshots, volumes, +templates, and ISOs. + +.. image:: /_static/images/secondary-storage-file-browser.png + :align: center + :alt: File browser for secondary storage + +.. note:: + If files or folders are not associated with a cloudstack resource, it doesn't mean that they are not used by cloudstack. + + +Migration of data between secondary storages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One may choose to completely migrate the data or migrate data such that the stores are balanced by choosing the appropriate Migration Policy. In order to facilitate distributing the migration load, SSVMs are spawned up if a file transfer takes more than a defined threshold. Following are the Global setting values to one may @@ -210,15 +429,119 @@ want to look at before proceeding with the migration task: | max.data.migration.wait.time | Maximum wait time for a data migration task before spawning a new SSVM | +----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +Selective migration of templates and snapshots across secondary storages is also +possible using the `migrateResourceToAnotherSecondaryStorage` command. Or via UI +under "Browser" tab for a secondary storage. + +Read only +~~~~~~~~~ + Secondary storages can also be set to read-only in order to cordon it off -from being used for storing any further templates, volumes and snapshots. +from being used for storing any further Templates, Volumes and Snapshots. + +.. code:: bash + + cmk updateImageStore id=4440f406-b9b6-46f1-93a4-378a75cf15de readonly=true + +Direct resources to a specific secondary storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, ACS allocates ISOs, volumes, snapshots, and templates to the freest secondary storage of the zone. In order to direct these resources to a specific secondary storage, the user can utilize the functionality of the dynamic secondary storage selectors using heuristic rules. This functionality utilizes JavaScript rules, defined by the user, to direct these resources to a specific secondary storage. When creating the heuristic rule, the script will have access to some preset variables with information about the secondary storage in the zone, about the resource the rule will be applied upon, and about the account that triggered the allocation. These variables are presented in the table below: + + +-----------------------------------+-----------------------------------+ + | Resource | Variables | + +===================================+===================================+ + | Secondary Storage | ``id`` | + | +-----------------------------------+ + | | ``name`` | + | +-----------------------------------+ + | | ``usedDiskSize`` | + | +-----------------------------------+ + | | ``totalDiskSize`` | + | +-----------------------------------+ + | | ``protocol`` | + +-----------------------------------+-----------------------------------+ + | Snapshot | ``size`` | + | +-----------------------------------+ + | | ``hypervisorType`` | + | +-----------------------------------+ + | | ``name`` | + +-----------------------------------+-----------------------------------+ + | ISO/Template | ``format`` | + | +-----------------------------------+ + | | ``hypervisorType`` | + | +-----------------------------------+ + | | ``templateType`` | + | +-----------------------------------+ + | | ``name`` | + +-----------------------------------+-----------------------------------+ + | Volume | ``size`` | + | +-----------------------------------+ + | | ``format`` | + +-----------------------------------+-----------------------------------+ + | Account | ``id`` | + | +-----------------------------------+ + | | ``name`` | + | +-----------------------------------+ + | | ``domain.id`` | + | +-----------------------------------+ + | | ``domain.name`` | + +-----------------------------------+-----------------------------------+ + +To utilize this functionality, the user needs to create a selector, using the API ``createSecondaryStorageSelector``. Each selector created specifies the type of resource the heuristic rule will be verified upon allocation (e.g. ISO, snapshot, template or volume), and the zone the heuristic will be applied on. It is noteworthy that can only be one heuristic rule for the same type within a zone. Another thing to consider is that the heuristic rule should return the ID of a valid secondary storage. Below, some examples are presented for heuristic rules considering different scenarios: + +1. Allocate a resource type to a specific secondary storage. + +.. code:: javascript + + function findStorageWithSpecificId(pool) { + return pool.id === '7432f961-c602-4e8e-8580-2496ffbbc45d'; + } + + secondaryStorages.filter(findStorageWithSpecificId)[0].id + +2. Dedicate storage pools for a type of template format. + +.. code:: javascript + + function directToDedicatedQCOW2Pool(pool) { + return pool.id === '7432f961-c602-4e8e-8580-2496ffbbc45d'; + } + + function directToDedicatedVHDPool(pool) { + return pool.id === '1ea0109a-299d-4e37-8460-3e9823f9f25c'; + } + + if (template.format === 'QCOW2') { + secondaryStorages.filter(directToDedicatedQCOW2Pool)[0].id + } else if (template.format === 'VHD') { + secondaryStorages.filter(directToDedicatedVHDPool)[0].id + } + +3. Direct snapshot of volumes with the KVM hypervisor to a specific secondary storage. + +.. code:: javascript + + if (snapshot.hypervisorType === 'KVM') { + '7432f961-c602-4e8e-8580-2496ffbbc45d'; + } + +4. Direct resources to a specific domain: + +.. code:: javascript + + if (account.domain.id == '52d83793-26de-11ec-8dcf-5254005dcdac') { + '1ea0109a-299d-4e37-8460-3e9823f9f25c' + } else if (account.domain.id == 'c1186146-5ceb-4901-94a1-dd1d24bd849d') { + '7432f961-c602-4e8e-8580-2496ffbbc45d' + } Working With Volumes -------------------- -A volume provides storage to a guest VM. The volume can provide for a +A volume provides storage to a Guest Instance. The volume can provide for a root disk or an additional data disk. CloudStack supports additional -volumes for guest VMs. +volumes for Guest Instances. Volumes are created for a specific hypervisor type. A volume that has been attached to guest using one hypervisor type (e.g, XenServer) may @@ -226,15 +549,15 @@ not be attached to a guest that is using another hypervisor type, for example:vSphere, KVM. This is because the different hypervisors use different disk image formats. -CloudStack defines a volume as a unit of storage available to a guest -VM. Volumes are either root disks or data disks. The root disk has "/" +CloudStack defines a volume as a unit of storage available to a Guest +Instance. Volumes are either root disks or data disks. The root disk has "/" in the file system and is usually the boot device. Data disks provide -for additional storage, for example: "/opt" or "D:". Every guest VM has -a root disk, and VMs can also optionally have a data disk. End users can -mount multiple data disks to guest VMs. Users choose data disks from the -disk offerings created by administrators. The user can create a template +for additional storage, for example: "/opt" or "D:". Every Guest Instance has +a root disk, and Instances can also optionally have a data disk. End Users can +mount multiple data disks to Guest Instances. Users choose data disks from the +disk offerings created by administrators. The User can create a Template from a volume as well; this is the standard procedure for private -template creation. Volumes are hypervisor-specific: a volume from one +Template creation. Volumes are hypervisor-specific: a volume from one hypervisor type may not be used on a guest of another hypervisor type. .. note:: @@ -251,31 +574,31 @@ hypervisor type may not be used on a guest of another hypervisor type. Creating a New Volume ~~~~~~~~~~~~~~~~~~~~~ -You can add more data disk volumes to a guest VM at any time, up to the +You can add more data disk volumes to a Guest Instance at any time, up to the limits of your storage capacity. Both CloudStack administrators and -users can add volumes to VM instances. When you create a new volume, it +Users can add volumes to Instances. When you create a new volume, it is stored as an entity in CloudStack, but the actual storage resources are not allocated on the physical storage device until you attach the 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, +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). +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 +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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can create data volumes on local storage (supported with XenServer, -KVM, and VMware). The data volume is placed on the same host as the VM -instance that is attached to the data volume. These local data volumes -can be attached to virtual machines, detached, re-attached, and deleted +KVM, and VMware). The data volume is placed on the same host as the Instance, +that is attached to the data volume. These local data volumes +can be attached to Instances, detached, re-attached, and deleted just as with the other types of data volume. Local storage is ideal for scenarios where persistence of data volumes @@ -285,20 +608,20 @@ latency and cost reduction from using inexpensive local disks. In order for local volumes to be used, the feature must be enabled for the zone. -You can create a data disk offering for local storage. When a user -creates a new VM, they can select this disk offering in order to cause +You can create a data disk offering for local storage. When a User +creates a new Instance, they can select this disk offering in order to cause the data disk volume to be placed in local storage. -You can not migrate a VM that has a volume in local storage to a +You can not migrate an Instance that has a volume in local storage to a different host, nor migrate the volume itself away to a different host. If you want to put a host into maintenance mode, you must first stop any -VMs with local data volumes on that host. +Instances with local data volumes on that host. To Create a New Volume ^^^^^^^^^^^^^^^^^^^^^^ -#. Log in to the CloudStack UI as a user or admin. +#. Log in to the CloudStack UI as a User or admin. #. In the left navigation bar, click Storage. @@ -310,7 +633,7 @@ To Create a New Volume - Name. Give the volume a unique name so you can find it later. - Availability Zone. Where do you want the storage to reside? This - should be close to the VM that will use the volume. + should be close to the Instance that will use the volume. - Disk Offering. Choose the characteristics of the storage. @@ -321,14 +644,14 @@ To Create a New Volume #. To start using the volume, continue to Attaching a Volume -Uploading an Existing Volume to a Virtual Machine -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Uploading an Existing Volume to an Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Existing data can be made accessible to a virtual machine. This is -called uploading a volume to the VM. For example, this is useful to -upload data from a local file system and attach it to a VM. Root -administrators, domain administrators, and end users can all upload -existing volumes to VMs. +Existing data can be made accessible to an Instance. This is +called uploading a volume to the Instance. For example, this is useful to +upload data from a local file system and attach it to an Instance. Root +administrators, domain administrators, and end Users can all upload +existing volumes to Instances. The upload is performed using HTTP. The uploaded volume is placed in the zone's secondary storage @@ -345,7 +668,7 @@ To upload a volume: you are going to upload. After uploading the data disk, CloudStack will use this value to verify that no data corruption has occurred. -#. Log in to the CloudStack UI as an administrator or user +#. Log in to the CloudStack UI as an administrator or User #. In the left navigation bar, click Storage. @@ -357,7 +680,7 @@ To upload a volume: that can be shown in the UI. - Availability Zone. Choose the zone where you want to store the - volume. VMs running on hosts in this zone can attach the volume. + volume. Instances running on hosts in this zone can attach the volume. - Format. Choose one of the following to indicate the disk image format of the volume. @@ -389,9 +712,9 @@ To upload a volume: Attaching a Volume ~~~~~~~~~~~~~~~~~~ -You can attach a volume to a guest VM to provide extra disk storage. +You can attach a volume to a Guest Instance to provide extra disk storage. Attach a volume when you first create a new volume, when you are moving -an existing volume from one VM to another, or after you have migrated a +an existing volume from one Instance to another, or after you have migrated a volume from one storage pool to another. #. Log in to the CloudStack UI as a user or admin. @@ -403,13 +726,13 @@ volume from one storage pool to another. #. Click the volume name in the Volumes list, then click the Attach Disk button |AttachDiskButton.png| -#. In the Instance popup, choose the VM to which you want to attach the - volume. You will only see instances to which you are allowed to - attach volumes; for example, a user will see only instances created +#. In the Instance popup, choose the Instance to which you want to attach the + volume. You will only see Instances to which you are allowed to + attach volumes; for example, a user will see only Instances created by that user, but the administrator will have more choices. #. When the volume has been attached, you should be able to see it by - clicking Instances, the instance name, and View Volumes. + clicking Instances, the Instance name, and View Volumes. Detaching and Moving Volumes @@ -417,62 +740,62 @@ Detaching and Moving Volumes .. note:: This procedure is different from moving volumes from one storage pool - to another as described in `“VM Storage Migration” + to another as described in `“Instance Storage Migration” <#vm-storage-migration>`_. -A volume can be detached from a guest VM and attached to another guest. -Both CloudStack administrators and users can detach volumes from VMs and -move them to other VMs. +A volume can be detached from a Guest Instance and attached to another guest. +Both CloudStack administrators and users can detach volumes from Instances and +move them to other Instances. -If the two VMs are in different clusters, and the volume is large, it -may take several minutes for the volume to be moved to the new VM. +If the two Instances are in different clusters, and the volume is large, it +may take several minutes for the volume to be moved to the new Instance. #. Log in to the CloudStack UI as a user or admin. #. In the left navigation bar, click Storage, and choose Volumes in - Select View. Alternatively, if you know which VM the volume is - attached to, you can click Instances, click the VM name, and click + Select View. Alternatively, if you know which Instance the volume is + attached to, you can click Instances, click the Instance name, and click View Volumes. #. Click the name of the volume you want to detach, then click the Detach Disk button. |DetachDiskButton.png| -#. To move the volume to another VM, follow the steps in +#. To move the volume to another Instance, follow the steps in `“Attaching a Volume” <#attaching-a-volume>`_. -VM Storage Migration -~~~~~~~~~~~~~~~~~~~~ +Instance Storage Migration +~~~~~~~~~~~~~~~~~~~~~~~~~~ Supported in XenServer, KVM, and VMware. .. note:: - This procedure is different from moving disk volumes from one VM to + This procedure is different from moving disk volumes from one Instance to another as described in `“Detaching and Moving Volumes” <#detaching-and-moving-volumes>`_. -You can migrate a virtual machine’s root disk volume or any additional +You can migrate an Instance’s root disk volume or any additional data disk volume from one storage pool to another in the same zone. You can use the storage migration feature to achieve some commonly desired administration goals, such as balancing the load on storage -pools and increasing the reliability of virtual machines by moving them +pools and increasing the reliability of Instances by moving them away from any storage pool that is experiencing issues. -On XenServer and VMware, live migration of VM storage is enabled through +On XenServer and VMware, live migration of Instance storage is enabled through CloudStack support for XenMotion and vMotion. Live storage migration -allows VMs to be moved from one host to another, where the VMs are not +allows Instances to be moved from one host to another, where the Instances are not located on storage shared between the two hosts. It provides the option -to live migrate a VM’s disks along with the VM itself. It is possible to -migrate a VM from one XenServer resource pool / VMware cluster to -another, or to migrate a VM whose disks are on local storage, or even to -migrate a VM’s disks from one storage repository to another, all while -the VM is running. +to live migrate an Instance’s disks along with the Instance itself. It is possible to +migrate an Instance from one XenServer resource pool / VMware cluster to +another, or to migrate an Instance whose disks are on local storage, or even to +migrate an Instance’s disks from one storage repository to another, all while +the Instance is running. .. note:: - Because of a limitation in VMware, live migration of storage for a - VM is allowed only if the source and target storage pool are - accessible to the source host; that is, the host where the VM is + Because of a limitation in VMware, live migration of storage for an + Instance is allowed only if the source and target storage pool are + accessible to the source host; that is, the host where the Instance is running when the live migration operation is requested. @@ -482,25 +805,25 @@ Migrating a Data Volume to a New Storage Pool There are two situations when you might want to migrate a disk: - Move the disk to new storage, but leave it attached to the same - running VM. + running Instance. -- Detach the disk from its current VM, move it to new storage, and - attach it to a new VM. +- Detach the disk from its current Instance, move it to new storage, and + attach it to a new Instance. -Migrating Storage For a Running VM -'''''''''''''''''''''''''''''''''' +Migrating Storage For a Running Instance +'''''''''''''''''''''''''''''''''''''''' -(Supported on XenServer and VMware) +(Supported on XenServer, KVM and VMware) #. Log in to the CloudStack UI as a user or admin. -#. In the left navigation bar, click Instances, click the VM name, and +#. In the left navigation bar, click Instances, click the Instance name, and click View Volumes. #. Click the volume you want to migrate. -#. Detach the disk from the VM. See `“Detaching and +#. Detach the disk from the Instance. See `“Detaching and Moving Volumes” <#detaching-and-moving-volumes>`_ but skip the “reattach” step at the end. You will do that after migrating to new storage. @@ -511,12 +834,12 @@ Migrating Storage For a Running VM Ready. -Migrating Storage and Attaching to a Different VM -''''''''''''''''''''''''''''''''''''''''''''''''' +Migrating Storage and Attaching to a Different Instance +''''''''''''''''''''''''''''''''''''''''''''''''''''''' #. Log in to the CloudStack UI as a user or admin. -#. Detach the disk from the VM. See `“Detaching and +#. Detach the disk from the Instance. See `“Detaching and Moving Volumes” <#detaching-and-moving-volumes>`_ but skip the “reattach” step at the end. You will do that after migrating to new storage. @@ -528,40 +851,61 @@ Migrating Storage and Attaching to a Different VM navigation bar. Make sure that Volumes is displayed at the top of the window, in the Select View dropdown. -#. Attach the volume to any desired VM running in the same cluster as +#. Attach the volume to any desired Instance running in the same cluster as the new storage server. See `“Attaching a Volume” <#attaching-a-volume>`_ -Migrating a VM Root Volume to a New Storage Pool -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Migrating an Instance Volume to a New Storage Pool +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -(XenServer, VMware) You can live migrate a VM's root disk from one -storage pool to another, without stopping the VM first. +(XenServer, VMware) You can live migrate an Instance's volumes from one +storage pool to another, without stopping the Instance first. -(KVM) When migrating the root disk volume, the VM must first be stopped, -and users can not access the VM. After migration is complete, the VM can -be restarted. +(KVM) KVM does not support volume live migration due to the limited possibility +to refresh VM XML domain. Therefore, to live migrate a volume between storage pools, +one must migrate the VM to a different host as well to force the VM XML domain update. +Use 'migrateVirtualMachineWithVolumes' instead or stop the Instance and then migrate +the volume. #. Log in to the CloudStack UI as a user or admin. -#. In the left navigation bar, click Instances, and click the VM name. +#. In the left navigation bar, click Instances, and click the Instance name. -#. (KVM only) Stop the VM. +#. (KVM only) Stop the Instance. #. Click the Migrate button |Migrateinstance.png| and choose the destination from the dropdown list. .. note:: - If the VM's storage has to be migrated along with the VM, this will + If the Instance's storage has to be migrated along with the Instance, this will be noted in the host list. CloudStack will take care of the storage migration for you. #. Watch for the volume status to change to Migrating, then back to Running (or Stopped, in the case of KVM). This can take some time. -#. (KVM only) Restart the VM. +#. (KVM only) Restart the Instance. + .. note:: + In case of KVM and PowerFlex/ScaleIO storage, live migration of + Instance's root disk is allowed from one PowerFlex/ScaleIO storage pool + to another, without stopping the Instance. + +Finding Primary Storage for Migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you click on migrate volume, CloudStack lists the available primary +storage. CloudStack uses its storage pool allocators to identify the primary +storages that are available and returns a list that is suitable for the selected +volume's migration. +The list also could include primary storages that are mentioned as +'Not suitable'. The criteria for which the primary storages are not suitable are: +- Storage tag mismatch with the volume. +- Doesn't have enough capacity. +- Reached its disable threshold. +- Disabled. +- Mismatch in the type of storage such as shared /Local. Resizing Volumes ~~~~~~~~~~~~~~~~ @@ -588,7 +932,7 @@ shrinking volumes is not supported on VMware hosts. Before you try to resize a volume, consider the following: -- The VMs associated with the volume are stopped. +- The Instances associated with the volume are stopped. - The data disks associated with the volume are removed. @@ -627,17 +971,17 @@ To resize a volume: Root Volume size defined via Service Offering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a Service Offering is created with a root disk size, then resizing the Root volume is possible only by resizing the VMs service offering. +If a Service Offering is created with a root disk size, then resizing the Root volume is possible only by resizing the Instances service offering. Service offering Root resizing constrains: -#. Users cannot deploy VMs with custom root disk size when using such offerings +#. Users cannot deploy Instances with custom root disk size when using such offerings -#. Users cannot resize the VM root disk size when using such offerings +#. Users cannot resize the Instance root disk size when using such offerings -#. The Root Volume of such VMs can only be resized when changing to another Service Offering with a Root disk size equals or larger than the current one. +#. The Root Volume of such Instances can only be resized when changing to another Service Offering with a Root disk size equals or larger than the current one. -#. Users can change the VM offering to a service offering with a Root size of 0GB (default) and then customize the volume size. +#. Users can change the Instance offering to a service offering with a Root size of 0GB (default) and then customize the volume size. The following table shows possible combinations of Service offering supported resizing based on the offering Root disk size: @@ -659,31 +1003,110 @@ The following table shows possible combinations of Service offering supported re Shrinking the Root disk is not supported via the service offering resizing workflow. All the combinations above assume a transition to Root disks with size equals or bigger than the original. Service Offerings with Root size of 0GB do not change the disk size to Zero and indicates that the offering do not enforces a Root disk size. -Reset VM to New Root Disk on Reboot +Change disk offering for volume ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There are volume operations like migrate volume and resize volume and both accepts new disk offering to replace the existing disk offering of volume. +Instead of using these APIs directly, the operation can be performed in the UI using change offering in the details view for the volume. +Upon changing the disk offering the volume will be resized and/or migrated to the suitable storage pool if required according to the new disk offering. + +The zone level setting "match.storage.pool.tags.with.disk.offering" gives flexibility or control to choose the new disk offering. +If this setting is true, then the new disk offering should have the same storage tags as the exiting disk offering of the volume. + +To change the disk offering of a volume: + +#. Log in to the CloudStack UI as a user or admin. + +#. In the left navigation bar, click Storage. + +#. In Select View, choose Volumes. + +#. Select the volume name in the Volumes list, then click the Change Offering for Volume button + +#. In the Change Offering For Volume pop-up, choose desired disk offering for the + volume. + + |change-offering-for-volume.png| + + #. If you select Custom Disk, specify a custom size. + + #. Enable or Disable "Auto migrate to another storage pool if required" as needed + +#. Click OK. + +Reset Instance to New Root Disk on Reboot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can specify that you want to discard the root disk and create a new -one whenever a given VM is rebooted. This is useful for secure +one whenever a given Instance is rebooted. This is useful for secure environments that need a fresh start on every boot and for desktops that -should not retain state. The IP address of the VM will not change due to +should not retain state. The IP address of the Instance will not change due to this operation. -**To enable root disk reset on VM reboot:** +**To enable root disk reset on Instance reboot:** When creating a new service offering, set the parameter isVolatile to -True. VMs created from this service offering will have their disks reset +True. Instances created from this service offering will have their disks reset upon reboot. See `“Creating a New Compute Offering” `_. +Volume delete protection +~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack protects volumes from accidental deletion using a delete protection +flag, which is false by default. When delete protection is enabled for a volume, +it cannot be deleted through the UI or API. It can only be deleted after +removing delete protection from the volume. + +Delete protection can be enabled for a volume via updateVirtualMachine API. + +.. code:: bash + + cmk update volume id= deleteprotection=true + +To remove delete protection, use the following command: + +.. code:: bash + + cmk update volume id= deleteprotection=false + +To enable/disable delete protection for a volume using the UI, follow these steps: + +#. Log in to the CloudStack UI as a User or admin. + +#. In the navigation menu on the left, click Volumes under Storage. + +#. Choose the volume for which you want to enable/disable delete protection. + +#. Click on the Edit button |EditButton.png| + +#. Toggle the Delete Protection switch to enable or disable delete protection. + +#. Click Ok button to save the changes. + +.. note:: + The volume delete protection is only considered when the volume is being + deleted through the UI or via `deleteVolume` or `destroyVolume` API. If the + domain/project is deleted, the volumes under the domain/project will be + deleted irrespective of the delete protection status. + Volume Deletion and Garbage Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The deletion of a volume does not delete the snapshots that have been -created from the volume +The deletion of a volume does not delete the Snapshots that have been +created from the volume. + +When an Instance is destroyed, data disk volumes that are attached to the Instance +are not deleted unless specified. -When a VM is destroyed, data disk volumes that are attached to the VM -are not deleted. +In managed storage systems such as Solidfire and others, the volume Snapshots +are linked entities in the volumes wherein deletion of the volume would delete +those Snapshots. In such managed storage systems, the volume Snapshots exist on +the primary storage and may not be backed up to the secondary storages. For a +volume deleted in CloudStack, it will not be deleted on the managed storage +(such as Solidfire and others) until all the volume Snapshots are deleted in +CloudStack. Volumes are permanently destroyed using a garbage collection process. The global configuration variables expunge.delay and expunge.interval @@ -698,6 +1121,158 @@ determine when the physical deletion of volumes will occur. Administrators should adjust these values depending on site policies around data retention. +Volume Metrics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Volume statistics are collected on a regular interval (defined by global +setting volume.stats.interval with a default of 600 seconds). +This feature is currently only available for VMware and KVM. +Volume stats include include bytes/s and IO/s statistics as shown in the +API output below. + +.. code:: bash + + [root@mgmt]# cmk list volumesmetrics id=272c3d8b-ef2c-499e-abfb-736b54d3d6b1 + { + "count": 1, + "volume": [ + { + ... + "diskiopstotal": 30245, + "diskioread": 22443, + "diskiowrite": 7802, + "diskkbsread": 343124, + "diskkbswrite": 217619, + ... + +Bytes read/write, as well as the total IO/s, are exposed via UI, as shown in the image below. + +|volume-metrics.png| + +These statistics are obtained from the hypervisor directly and they represent +"current" bytes/s and IO/s values at the time of collection. + +Check and repair Volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When there are any leaks or any inconsistencies in the volume, then the checkVolume API can be used to +check for any such errors in the volume and helps in repairing them. This feature is currently available only +for KVM and volumes with QCOW2 format. This API uses "qemu-img check" command on the KVM host. + +Also, a global or storage pool level setting "volume.check.and.repair.leaks.before.use" is available which allows +to check and repair any leaks of the volume during instance start and volume attach operations. +This will help in repairing any leaks of the volume before using it. This is a blocking operation, meaning +instance start or volume attach will be performed only after the check and repair operation is completed. +The setting helps in defining whether to allow this operation or not. + +checkVolume API takes two parameters as input + +- "id" for the volume UUID + +- "repair" an optional parameter whether to repair the volume or not. Parameter takes "leaks" or "all" as the input. + +Following is the example for checkVolume API usage and the result in the volume response. + +.. code:: bash + + [root@mgmt]# cmk check volume id=55937826-2f08-414a-9eef-4c6b7d6fd3b1 repair=leaks + { + . + . + "volumecheckresult": { + "allocated-clusters": "110", + "check-errors": "0", + "leaks": 73, + "filename": "/mnt/e72364b6-eab0-369f-af0b-2ec8bed9d8ac/55937826-2f08-414a-9eef-4c6b7d6fd3b1", + "format": "qcow2", + "fragmented-clusters": "32", + "image-end-offset": "7995392", + "total-clusters": "131072" + }, + "volumerepairresult": { + "allocated-clusters": "110", + "check-errors": "0", + "leaks-fixed": 73, + "filename": "/mnt/e72364b6-eab0-369f-af0b-2ec8bed9d8ac/55937826-2f08-414a-9eef-4c6b7d6fd3b1", + "format": "qcow2", + "fragmented-clusters": "32", + "image-end-offset": "7995392", + "total-clusters": "131072" + }, + } + + +Importing and Unmanaging Volumes from Storage Pools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since Apache CloudStack 4.19.1.0, importing and unmanaging volumes from primary storage pools are supported. + +.. note:: + Currently the supported storage types are: NFS, Ceph and Local storage for KVM hypervisor. + +#. Log in to the CloudStack UI as an administrator. + +#. In the left navigation bar, click *Tools > Import DATA Volumes* section. + +#. Select the scope of the storage pool (Zone, Cluster, Host). + +#. Select the zone/pod/cluster/host of the storage pool. + +#. Select the storage pool. + +#. The unmanaged volumes on the storage pool are listed on the left panel. + +#. The managed volumes on the storage pool are listed on the right panel. + +|list-unmanaged-managed-volumes.png| + +To import a volume: + +#. select a unmanaged volume from the left panel, click "Import Volume" icon. + +#. In the Import Volume pop-up, select the Account Type, Domain/Account/Project and a disk offering. + +#. Click OK. + +|import-volume.png| + +.. note:: + - The volume to be imported must be placed in the root directory of the storage pool. + + - The format of the volume must be QCOW2 on NFS/Local storage, and RAW on Ceph storage. + + - The volume must not be encrypted. + + - The volume must not be locked. + + - The volume must not have a backing file. + + +.. note:: + By default, the volume is imported for the caller if Domain/Account/Project are not set. By default, the imported volumes use the default disk offering "Default Custom Offering for Volume Import" + (on Shared storages) or "Default Custom Offering for Volume Import - Local" (on Local storages). + +To unmanage volume(s): + +#. select the volumes to be unmanaged from the right panel + +#. click "Unmanage Volume" or "Unmanage Volumes" icon + +#. click OK in the confirmation dialog. + +|unmanage-volume.png| + +.. note:: + - The volume to be unmanaged must not be attached to any VM as ROOT disk or DATA disk. + + - The volume to be umnanaged must be at Ready state. + + - The volume must not be encrypted. + + - The volume must not be locked by another process. + + - The volume must not have a backing file. + Working with Volume Snapshots ----------------------------- @@ -705,29 +1280,34 @@ Working with Volume Snapshots (Supported for the following hypervisors: **XenServer**, **VMware vSphere**, and **KVM**) -CloudStack supports snapshots of disk volumes. Snapshots are a -point-in-time capture of virtual machine disks. Memory and CPU states +CloudStack supports Snapshots of disk volumes. Snapshots are a +point-in-time capture of Instance disks. Memory and CPU states are not captured. If you are using the Oracle VM hypervisor, you can not -take snapshots, since OVM does not support them. +take Snapshots, since OVM does not support them. Snapshots may be taken for volumes, including both root and data disks (except when the Oracle VM hypervisor is used, which does not support -snapshots). The administrator places a limit on the number of stored -snapshots per user. Users can create new volumes from the snapshot for -recovery of particular files and they can create templates from -snapshots to boot from a restored disk. - -Users can create snapshots manually or by setting up automatic recurring -snapshot policies. Users can also create disk volumes from snapshots, -which may be attached to a VM like any other disk volume. Snapshots of +Snapshots). The administrator places a limit on the number of stored +Snapshots per user. Users can create new volumes from the Snapshot for +recovery of particular files and they can create Templates from +Snapshots to boot from a restored disk. + +Users can create Snapshots manually or by setting up automatic recurring +Snapshot policies. Users can also create disk volumes from Snapshots, +which may be attached to an Instance like any other disk volume. Snapshots of both root disks and data disks are supported. However, CloudStack does -not currently support booting a VM from a recovered root disk. A disk -recovered from snapshot of a root disk is treated as a regular data +not currently support booting a Instance from a recovered root disk. A disk +recovered from Snapshot of a root disk is treated as a regular data disk; the data on recovered disk can be accessed by attaching the disk -to a VM. +to an Instance. + +A completed Snapshot is copied from primary storage to secondary +storage, where it is stored until deleted or purged by newer Snapshot. -A completed snapshot is copied from primary storage to secondary -storage, where it is stored until deleted or purged by newer snapshot. +Users can also select the desired zones at the time of taking manual snapshots +or while creating a snapshot policy. When additional zone(s) are selected and +snapshot backup is allowed, the snapshot will be first copied to the secondary +storage of the native zone and then copied to the additional zone(s) from there. How to Snapshot a Volume ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -738,24 +1318,31 @@ How to Snapshot a Volume #. In Select View, be sure Volumes is selected. -#. Click the name of the volume you want to snapshot. +#. Click the name of the volume you want to Snapshot. #. 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 +In recent CloudStack versions, by default, creating a Volume Snapshot for a running Instance is disabled +due to a possible volume corruption in certain cases. To enable creating a Volume Snapshots while the Instance is running, the global setting 'kvm.snapshot.enabled' must be set to 'True'. -The volume snapshot creation has changed in recent versions: +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. +When the VM is running, a disk-only VM snapshot is taken, exclusively for the volume in question. +If the VM is stopped, the volume will be converted (with qemu-img convert). The final storage location is +determined by the ``snapshot.backup.to.secondary`` configuration; if it is false the snapshot will be copied +to a different directory in the same primary storage as the volume; if it is true the snapshot will be copied +to the secondary storage. If the snapshot is being taken in a file-based storage (NFS, SharedMountPoint, Local), +it will be copied directly to its final storage location, according to the configuration. + +Since 4.21.0.0, ACS supports incremental snapshots for the KVM hypervisor when using file-based storage (NFS, SharedMountPoint, Local), +to enable incremental snapshots the ``kvm.incremental.snapshot`` configuration must be enabled. Furthermore, in order to take incremental snapshots +the KVM host must have at least Libvirt version 7.6.0+ and qemu version 6.1+. The size of the snapshot chains +will be determined by the ``snapshot.delta.max`` configuration, which affects both KVM and XenServer snapshots. +More information on the incremental snapshot feature for KVM can be found in its `specification `_. Automatic Snapshot Creation and Retention @@ -764,20 +1351,20 @@ Automatic Snapshot Creation and Retention (Supported for the following hypervisors: **XenServer**, **VMware vSphere**, and **KVM**) -Users can set up a recurring snapshot policy to automatically create -multiple snapshots of a disk at regular intervals. Snapshots can be -created on an hourly, daily, weekly, or monthly interval. One snapshot +Users can set up a recurring Snapshot policy to automatically create +multiple Snapshots of a disk at regular intervals. Snapshots can be +created on an hourly, daily, weekly, or monthly interval. One Snapshot policy can be set up per disk volume. For example, a user can set up a -daily snapshot at 02:30. +daily Snapshot at 02:30. -With each snapshot schedule, users can also specify the number of -scheduled snapshots to be retained. Older snapshots that exceed the +With each Snapshot schedule, users can also specify the number of +recurring Snapshots to be retained. Older Snapshots that exceed the retention limit are automatically deleted. This user-defined limit must be equal to or lower than the global limit set by the CloudStack administrator. See `“Globally Configured Limits” `_. The limit applies only -to those snapshots that are taken as part of an automatic recurring -snapshot policy. Additional manual snapshots can be created and +to those Snapshots that are taken as part of an automatic recurring +Snapshot policy. Additional manual Snapshots can be created and retained. @@ -785,7 +1372,7 @@ Incremental Snapshots and Backup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Snapshots are created on primary storage where a disk resides. After a -snapshot is created, it is immediately backed up to secondary storage +Snapshot is created, it is immediately backed up to secondary storage and removed from primary storage for optimal utilization of space on primary storage. @@ -797,81 +1384,109 @@ incremental backups are supported, every N backup is a full backup. +------------------------------+------------------+------------------+-----+ | | VMware vSphere | Citrix XenServer | KVM | +==============================+==================+==================+=====+ -| Support incremental backup | No | Yes | No | +| Support incremental backup | No | Yes | Yes | +------------------------------+------------------+------------------+-----+ + .. note:: + Between versions 4.17.x, 4.18.0 and 4.18.1, KVM volume snapshot backups were not full snapshots and they rely on the snapshots on the primary storage. To prevent any loss of data, care must be taken during revert operation and it must be ensured that the source primary storage snapshot file is present. + Volume Status ~~~~~~~~~~~~~ -When a snapshot operation is triggered by means of a recurring snapshot -policy, a snapshot is skipped if a volume has remained inactive since -its last snapshot was taken. A volume is considered to be inactive if it -is either detached or attached to a VM that is not running. CloudStack -ensures that at least one snapshot is taken since the volume last became +When a Snapshot operation is triggered by means of a recurring Snapshot +policy, a Snapshot is skipped if a volume has remained inactive since +its last Snapshot was taken. A volume is considered to be inactive if it +is either detached or attached to an Instance that is not running. CloudStack +ensures that at least one Snapshot is taken since the volume last became inactive. -When a snapshot is taken manually, a snapshot is always created +When a Snapshot is taken manually, a Snapshot is always created regardless of whether a volume has been active or not. Snapshot Restore ~~~~~~~~~~~~~~~~ -There are two paths to restoring snapshots. Users can create a volume -from the snapshot. The volume can then be mounted to a VM and files -recovered as needed. Alternatively, a template may be created from the -snapshot of a root disk. The user can then boot a VM from this template +There are two paths to restoring Snapshots. Users can create a volume +from the Snapshot. The volume can then be mounted to an Instance and files +recovered as needed. Alternatively, a Template may be created from the +Snapshot of a root disk. The user can then boot an Instance from this Template to effect recovery of the root disk. +Some hypervisor and storage combinations also allow for Instances and volumes +to be reverted from snapshots. In such cases the **Revert to snapshot** action for +a snapshot in the UI or the `revertSnapshot` API can be used to restore the volume +to a particular snapshot. It should be noted that, when supported by the combination +of hypervisor and storage, the snapshot must be available in the zone in which volume +to be restored is present. + +.. note:: + When creating a volume from a snapshot of a DATA disk, it should be noted that + the volume's disk offering must be accessible in the target zone. In case the disk + offering is using storage tags then such tagged storage resources must be available + in the target zone. + + Snapshot Job Throttling ~~~~~~~~~~~~~~~~~~~~~~~ -When a snapshot of a virtual machine is requested, the snapshot job runs -on the same host where the VM is running or, in the case of a stopped -VM, the host where it ran last. If many snapshots are requested for VMs -on a single host, this can lead to problems with too many snapshot jobs +When a Snapshot of an Instance is requested, the Snapshot job runs +on the same host where the Instance is running or, in the case of a stopped +Instance, the host where it ran last. If many Snapshots are requested for Instances +on a single host, this can lead to problems with too many Snapshot jobs overwhelming the resources of the host. To address this situation, the cloud's root administrator can throttle -how many snapshot jobs are executed simultaneously on the hosts in the +how many Snapshot jobs are executed simultaneously on the hosts in the cloud by using the global configuration setting concurrent.snapshots.threshold.perhost. By using this setting, the -administrator can better ensure that snapshot jobs do not time out and +administrator can better ensure that Snapshot jobs do not time out and hypervisor hosts do not experience performance issues due to hosts being -overloaded with too many snapshot requests. +overloaded with too many Snapshot requests. Set concurrent.snapshots.threshold.perhost to a value that represents a -best guess about how many snapshot jobs the hypervisor hosts can execute +best guess about how many Snapshot jobs the hypervisor hosts can execute at one time, given the current resources of the hosts and the number of -VMs running on the hosts. If a given host has more snapshot requests, -the additional requests are placed in a waiting queue. No new snapshot -jobs will start until the number of currently executing snapshot jobs +Instances running on the hosts. If a given host has more Snapshot requests, +the additional requests are placed in a waiting queue. No new Snapshot +jobs will start until the number of currently executing Snapshot jobs falls below the configured limit. The admin can also set job.expire.minutes to place a maximum on how long -a snapshot request will wait in the queue. If this limit is reached, the -snapshot request fails and returns an error message. +a Snapshot request will wait in the queue. If this limit is reached, the +Snapshot request fails and returns an error message. + + +Snapshot Copy +~~~~~~~~~~~~~ + +CloudStack allows copying an existing backed-up snapshot to multiple zones. +Users can either use the UI in the snapshot details view or the `copySnapshot` +API to copy a snapshot from one zone to other zone(s). Snapshot copies can +be used for disastser recovery and creating volumes and templates in the +specific zone. Later if not needed, these copies or replicas can be individually +deleted without affecting other replicas. VMware Volume Snapshot Performance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you take a snapshot of a data or root volume on VMware, CloudStack +When you take a Snapshot of a data or root volume on VMware, CloudStack uses an efficient storage technique to improve performance. -A snapshot is not immediately exported from vCenter to a mounted NFS +A Snapshot is not immediately exported from vCenter to a mounted NFS share and packaged into an OVA file format. This operation would consume time and resources. Instead, the original file formats (e.g., VMDK) provided by vCenter are retained. An OVA file will only be created as needed, on demand. To generate the OVA, CloudStack uses information in a properties file (\*.ova.meta) which it stored along with the original -snapshot data. +Snapshot data. .. note:: For upgrading customers: This process applies only to newly created - snapshots after upgrade to CloudStack 4.2. Snapshots that have already + Snapshots after upgrade to CloudStack 4.2. Snapshots that have already been taken and stored in OVA format will continue to exist in that format, and will continue to work as expected. @@ -882,13 +1497,13 @@ Linstor Primary Storage LINSTOR is a configuration management system for storage on Linux systems. It manages LVM logical volumes and/or ZFS ZVOLs on a cluster of nodes. It leverages DRBD for replication between different nodes and to provide block storage devices -to users and applications. It manages snapshots, encryption and caching of HDD backed data in SSDs via bcache. +to users and applications. It manages Snapshots, encryption and caching of HDD backed data in SSDs via bcache. LINSTOR can be used as volume storage provider for Cloudstack, it currently only supports KVM hypervisors. To get started first setup your LINSTOR cluster according to the `LINSTOR User Guide `_ .. note:: - Make sure a LINSTOR-Satellite is running on all nodes where you want to have a storage provided for you VM's + Make sure a LINSTOR-Satellite is running on all nodes where you want to have a storage provided for you Instances and that the nodes have the exact same node names as the nodes in Cloudstack. Also add a resource group to LINSTOR which you intend to use in Cloudstack. @@ -897,6 +1512,183 @@ primary storage see :ref:`add-primary-storage`. For protocol choose ``Linstor`` and as server specify the controller REST-API URL e.g.: ``http://127.0.0.1:3370`` and use the resource group name you added in the LINSTOR cluster. +Object Storage +--------------- + +This section gives technical details about CloudStack +object storage. For more information about the concepts behind object storage +see :ref:`about-object-storage` . For information about how to install and configure +object storage through the CloudStack UI, see the in the Installation Guide. + + +Creating a New Bucket +~~~~~~~~~~~~~~~~~~~~~ + +Buckets are logical containers for storing objects. To create a New Bucket: + +#. Log in to the CloudStack UI as a user or administrator. + +#. In the left navigation bar, click Storage. + +#. In Select View, choose Buckets. + +To create a new bucket, click create Bucket, provide the following details, and click OK. + +#. Name: Give the bucket a unique name. + +#. Object Store: Select the object store where you want the Bucket to reside + +#. Quota in GiB: Enforce a quota on the bucket. This is a mandatory field since 4.21 as it is used to enforce resource limit on object store usage. + +Based on the selected Object Store, you can specify additional details like quota, encryption, policy. + +|Createbucket.png| + + +Browsing objects in a bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Once a bucket has been created, you can browse the files in the bucket by clicking the bucket name. +|bucket-details-browser-tab.png| + +2. Open the `Browser` tab to list files in the bucket. +|object-store-browser-tab.png| + +Under `Browser` tab, clicking a directory on the browser tab will list the objects in that directory. +For a file, clicking it list the properties of that file with links to access the file. +|object-store-file-properties.png| + +.. note:: + To access the bucket, UI uses the URL, access key and secret key from the bucket's details. + + +Uploading an object to a bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. On the `Browser` tab, click the |upload-button.png| button to upload a file to the bucket. This will open up a dialog box to select the file to upload. +|object-store-file-upload.png| + +2. Select the file you want to upload and specify the upload path & metadata for the object as per requirements. + +3. Click on `Upload` button to upload the file(s) to the bucket. + + +Deleting objects from a bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Select the files you want to remove from the bucket. + +2. Click on the |delete-button.png| button to delete the selected files from the bucket. + + +Configuring resource limits on buckets and object storage usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Administrators can enforce limits on the maximum number of buckets they can be created and +the total object storage space that can be allocated at an account, domain and project level. +Allocated storage is the sum of quota used by all of the buckets. +Administrators can do this by going to the configure limits tab in accounts, domains and projects +similar to when enforcing resource limits on volumes, primary storage usage etc. + +Shared FileSystems +------------------ + +CloudStack offers fully managed NFS Shared FileSystems to all users. +This section gives technical details on how to create/manage a Shared FileSystem +using basic lifecycle operations and also some implementation details. + +.. note:: + This feature is available only on advanced zones without security groups. + +Creating a New Shared FileSystem +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Log in to the CloudStack UI as a user or administrator. + +#. In the left navigation bar, click Storage. + +#. In the Select View, choose Shared FileSystems. + +Click on Create Shared FileSystem, provide the following details and then click OK. + +#. Name +#. Description +#. Zone +#. Format: Filesystem format (XFS, EXT4) which will be installed on the Shared FileSystem. +#. Network: Guest network to which the Shared FileSystem will be attached. +#. Compute offering: Offering using which the Shared FileSystem Instance will be deployed. +#. Disk offering: Offering used by the underlying data volume. +#. Size, MinIops and MaxIos: Displayed only when the disk offering takes custom size and custom iops. + +|create-sharedfs.png| + +Admins will see extra fields in the create form where they can specify the +account, domain and the project which will be owning the Shared FileSystem. +|create-sharedfs-admin.png| + +Access +~~~~~~ +The Shared FileSystem can be mounted by using the information given on the Access Tab. +|sharedfs-access-tab.png| + +Lifecycle Operations +~~~~~~~~~~~~~~~~~~~~ + +Supported lifecycle operations are : + +#. Update name and description of the Shared FileSystem + +#. Stop/Start Shared FileSystem - This will Stop and Start the Shared FileSystem Instance + +#. Restart Shared FileSystem - Reboots the Shared FileSystem Instance. If Cleanup option is provided then the + Instance state is cleaned up and restored to the original template. Configurations related to setting up the + NFS export will be done again. This will not affect the data on the volume attached to the Instance. + |restart-sharedfs.png| + +#. Change Disk Offering - The disk offering of the underlying volume can be changed. Whether live resize + is supported or not depends on the hyervisor. + Please note that the size of the Shared FileSystem can only be increased. + +#. Change Service Offering - The service offering of the Shared FileSystem Instance can be changed as required. + This can only be done when the Shared FileSystem is in Stopped state. + +#. Add/Remove Network - Guest networks can be added to or removed from the Shared FileSystem. + NFS share is exported to all networks. So instances on different networks can mount the + same share using the respective IP addresses as given on the Access tab. + APIs serving these operations are addNicToVirtualMachine and removeNicToVirtualMachine + called with the Shared FileSystem Instance ID. + Please note that the added networks must not be on overlapping CIDR ranges. + |add-remove-sharedfs-network.png| + +#. Destroy Shared FileSystem - The Shared FileSystem will be destroyed. It can be recovered before it automatically gets expunged. + Expunge timeout is given by the global setting 'sharedfs.cleanup.delay'. + + +Shared FileSystem Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Shared FileSystem Instance is stateless and HA enabled. A new instance is deployed and will start +serving the NFS share if the host or VM goes down. +The VM is installed with the SystemVM template which is also used by the CPVM and SSVM. + +The Shared FileSystem Instance can be seen in the Instances Tab as well. It's name is prefixed by the string +"sharedfs-" plus the Shared FileSystem name. Actions that might interfere with Shared FileSystem operations are blocked or not shown. +Basic operations like Start, Stop and Reboot are allowed for troubleshooting. +Users can access the VM using the 'View Console' button for troubleshooting although it is not +required during normal operations. + +Service Offering +~~~~~~~~~~~~~~~~ + +There are two global settings that control what should be the minimum RAM size and minimum +CPU count for the Shared FileSystem Instance : 'sharedfsvm.min.cpu.count' and 'sharedfsvm.min.ram.size`. +Only those offerings which meet these settings and have HA enabled are shown in the create form. + +Shared FileSystem Data Volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The data volume is also visible to the users. It is recommended to use the Shared FileSystem UI/API to +manage the data but users or admin can perform actions directly on the data volume or the root volume +as well if they wish. Attaching and detaching a disk is not allowed on a Shared FileSystem Instance. .. |AttachDiskButton.png| image:: /_static/images/attach-disk-icon.png :alt: Attach Disk Button. @@ -904,11 +1696,63 @@ and use the resource group name you added in the LINSTOR cluster. :alt: button to display the resize volume option. .. |resize-volume.png| image:: /_static/images/resize-volume.png :alt: option to resize a volume. +.. |change-offering-for-volume.png| image:: /_static/images/change-offering-for-volume.png + :alt: option to change offering for a volume. .. |SnapshotButton.png| image:: /_static/images/SnapshotButton.png :alt: Snapshot Button. .. |DetachDiskButton.png| image:: /_static/images/detach-disk-icon.png :alt: Detach Disk Button. .. |Migrateinstance.png| image:: /_static/images/migrate-instance.png :alt: button to migrate a volume. +.. |volume-metrics.png| image:: /_static/images/volume-metrics.png + :alt: Volume metrics .. |volume-from-snap.png| image:: /_static/images/volume-from-snap.png - :alt: Offering is needed when creating a volume from the ROOT volume snapshot. + :alt: Offering is needed when creating a volume from the ROOT Volume Snapshot. +.. |Createbucket.png| image:: /_static/images/add-bucket.png + :alt: Create Bucket +.. |bucket-details-browser-tab.png| image:: /_static/images/bucket-details-browser-tab.png + :alt: Bucket details browser tab +.. |object-store-browser-tab.png| image:: /_static/images/object-store-browser-tab.png + :alt: Object store browser tab +.. |object-store-file-properties.png| image:: /_static/images/object-store-file-properties.png + :alt: Object store file properties +.. |object-store-file-upload.png| image:: /_static/images/object-store-file-upload.png + :alt: Object store file upload +.. |delete-button.png| image:: /_static/images/delete-button.png + :alt: Delete button +.. |EditButton.png| image:: /_static/images/edit-icon.png + :alt: button to edit the properties of a volume +.. |upload-button.png| image:: /_static/images/upload-button.png + :alt: Upload button +.. |adding-local-pool-via-ui.png| image:: /_static/images/adding-local-pool-via-ui.png + :alt: Adding Local Storage Pool via UI +.. |change-storage-pool-scope-via-ui.png| image:: /_static/images/change-storage-pool-scope-via-ui.png + :alt: Change Primary Storage Scope via UI +.. |change-storage-pool-scope-to-zone.png| image:: /_static/images/change-storage-pool-scope-to-zone.png + :alt: Change Primary Storage Scope to Zone via UI +.. |list-unmanaged-managed-volumes.png| image:: /_static/images/list-unmanaged-managed-volumes.png + :alt: List of Unmanaged and Managed Volumes +.. |import-volume.png| image:: /_static/images/import-volume.png + :alt: Import Volume +.. |unmanage-volume.png| image:: /_static/images/unmanage-volume.png + :alt: Unmanage Volume +.. |create-sharedfs.png| image:: /_static/images/create-sharedfs.png + :alt: Create Shared FileSystem +.. |create-sharedfs-admin.png| image:: /_static/images/create-sharedfs-admin.png + :alt: Create Shared FileSystem Admin Options +.. |restart-sharedfs.png| image:: /_static/images/restart-sharedfs.png + :alt: Restart Shared FileSystem +.. |sharedfs-access-tab.png| image:: /_static/images/sharedfs-access-tab.png + :alt: Shared FileSystem Access Tab +.. |add-remove-sharedfs-network.png| image:: /_static/images/add-remove-sharedfs-network.png + :alt: Shared FileSystem Networks +.. |nfs-mount-options-create-zone-wizard.png| image:: /_static/images/nfs-mount-options-create-zone-wizard.png + :alt: NFS mount options in create Zone wizard +.. |nfs-mount-options-add-primary-storage.png| image:: /_static/images/nfs-mount-options-add-primary-storage.png + :alt: NFS mount options in add Primary Storage +.. |nfs-mount-options-edit-primary-storage.png| image:: /_static/images/nfs-mount-options-edit-primary-storage.png + :alt: NFS mount options in edit Primary Storage +.. |adding-storage-access-group-on-primary-storage.png| image:: /_static/images/adding-storage-access-group-on-primary-storage.png + :alt: Adding storage access groups on primary storage +.. |adding-storage-access-group-on-host.png| image:: /_static/images/adding-storage-access-group-on-host.png + :alt: Adding storage access groups on host diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst index c190a13e3c..ec0e00d298 100644 --- a/source/adminguide/systemvm.rst +++ b/source/adminguide/systemvm.rst @@ -14,20 +14,20 @@ under the License. -CloudStack uses several types of system virtual machines to perform +CloudStack uses several types of system Instances to perform tasks in the cloud. In general CloudStack manages these system VMs and creates, starts, and stops them as needed based on scale and immediate -needs. However, the administrator should be aware of them and their +needs. Unlike user VMs, system VMs are expunged on destroying them. However, the administrator should be aware of them and their roles to assist in debugging issues. The System VM Template ---------------------- -The System VMs come from a single template. The System VM has the +The System VMs come from a single Template. The System VM has the following characteristics: -- Debian 10.8(buster), 4.19.0 kernel with the latest security +- Debian 12(bookwork), 6.1.0 kernel with the latest security patches from the Debian security APT repository - Has a minimal set of packages installed thereby reducing the attack @@ -46,45 +46,99 @@ following characteristics: - Latest version of JRE from Sun/Oracle ensures improved security and speed +Starting with 4.20.0 release, the following architectures are supported for KVM +hypervisor: + +- Intel/AMD 64-bit (x86_64) + +- ARM 64-bit (aarch64) + +Other hypervisors only support Intel/AMD 64-bit (x86_64) + + +System VM Template bundled with packages +---------------------------------------- + +The System VM Template is bundled with the official release DEB and RPM +cloudstack-management packages for Intel/AMD 64-bit architecture and the +following hypervisors: + +- KVM + +- VMware + +- XenServer + +Currently, the ARM 64-bit template(s) are not bundled with the packages. + +During zone deployment and upgrade, the required templates, i.e., the +templates for hypervisor and architecture which are in use in the zone +if not already present will be automatically registered and seeded on +the secondary storage. + +Template(s) will be downloaded from the configured repository +and the same workflow for the registration and seeding will be used. +Repository for downloading the templates can be configured using +/etc/cloudstack/management/server.properties file by updating the +``system.vm.templates.download.repository`` property. If no custom +repository is configured, templates will be downloaded from the default +official repository. + +If the automatic download and seeding of template fails, the +template can be registered and seeded manually. +UI/API can be used to register the template if the secondary storage VM is +running in the zone. In case the secondary storage VM is not present then +manual registration and seeding can be done using ``cloud-install-sys-tmplt`` +script. + Changing the Default System VM Template --------------------------------------- -Using the 64-bit template should be use with a System Offering of at least 512MB +The 64-bit template should be used with a System Offering of at least 512MB of memory. -#. Based on the hypervisor you use, download the 64-bit template from +#. Based on the hypervisor you use, download the 64-bit Template - e.g. from the following location: .. cssclass:: table-striped table-bordered table-hover - ========== ================================================================================================ - Hypervisor Download Location - ========== ================================================================================================ - XenServer |sysvm64-url-xen| - KVM |sysvm64-url-kvm| - VMware |sysvm64-url-vmware| - Hyper-V |sysvm64-url-hyperv| - ========== ================================================================================================ + ========== ============ ================================================================================== + Hypervisor Architecture Download Location + ========== ============ ================================================================================== + XenServer x86_64 |sysvm64-url-xen| + KVM x86_64 |sysvm64-url-kvm| + KVM aarch64 |sysvm64-url-kvm-aarch64| + VMware x86_64 |sysvm64-url-vmware| + Hyper-V x86_64 |sysvm64-url-hyperv| + ========== ============ ================================================================================== #. As an administrator, log in to the CloudStack UI -#. Register the 64 bit template. +#. Register the 64-bit Template. For example: KVM64bitTemplate -#. While registering the template, select Routing. +#. While registering the Template, select Routing. -#. Navigate to Infrastructure > Zone > Settings. +#. Navigate to Configuration, Global Settings: -#. Set the name of the 64-bit template, KVM64bitTemplate, in the +#. Set the name of the 64-bit Template, KVM64bitTemplate, in the *``router.template.kvm``* global parameter. - If you are using a XenServer 64-bit template, set the name in the - *``router.template.xen``* global parameter. + If you are using a XenServer 64-bit Template, set the name in the + *``router.template.xenserver``* global parameter. + + If you are using a VMware 64-bit Template, set the name in the + *``router.template.vmware``* global parameter. Any new virtual router created in this Zone automatically picks up - this template. + this Template. + +#. When using multiple architectures in the Zone, same name can be used + for the templates for the different architectures and same hypervisor + to allow deployment across them depending on the compute capacity and + the zone setting - *system.vm.preferred.architecture* #. Restart the Management Server. @@ -100,7 +154,7 @@ 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. +~cloud/.ssh/id_rsa. #. Find the details of the System VM @@ -132,16 +186,16 @@ System VMs running on ESXi, the key is stored on the management server at Format: ssh -i -p 3922 - Example: root@management:~# ssh -i /var/lib/cloudstack/management/.ssh/id_rsa 172.16.0.250 -p 3922 + Example: root@management:~# ssh -i ~cloud/.ssh/id_rsa 172.16.0.250 -p 3922 Multiple System VM Support for VMware ------------------------------------- -Every CloudStack zone has single System VM for template processing tasks -such as downloading templates, uploading templates, and uploading ISOs. +Every CloudStack zone has single System VM for Template processing tasks +such as downloading Templates, uploading Templates, and uploading ISOs. In a zone where VMware is being used, additional System VMs can be -launched to process VMware-specific tasks such as taking snapshots and -creating private templates. The CloudStack management server launches +launched to process VMware-specific tasks such as taking Snapshots and +creating private Templates. The CloudStack management server launches additional System VMs for VMware-specific tasks as the load increases. The management server monitors and weights all commands sent to these System VMs and performs dynamic load balancing and scaling-up of more @@ -161,12 +215,12 @@ Clicking a console icon brings up a new window. The console viewer into that window refers to the public IP address of a console proxy VM. There is exactly one public IP address allocated per console proxy VM. The viewer application connects to this IP. The console proxy then proxies -the connection to the VNC port for the requested VM on the Host hosting +the connection to the VNC port for the requested instance on the Host hosting the guest. Since 4.15, noVNC has been integrated into the console proxy and is the default viewer. It inherently supports multiple keyboard layouts configured -in the guest virtual machine. Additionally, it can scale the display as +in the Guest Instance. Additionally, it can scale the display as well as paste into the console. noVNC is set as the default console viewer which be changed via the @@ -184,16 +238,67 @@ to the Management Server. The default reporting interval is five seconds. This can be changed through standard Management Server configuration with the parameter consoleproxy.loadscan.interval. -Assignment of guest VM to console proxy is determined by first -determining if the guest VM has a previous session associated with a +Assignment of Guest Instance to console proxy is determined by first +determining if the Guest Instance has a previous session associated with a console proxy. If it does, the Management Server will assign the guest -VM to the target Console Proxy VM regardless of the load on the proxy +instance to the target Console Proxy VM regardless of the load on the proxy VM. Failing that, the first available running Console Proxy VM that has the capacity to handle new sessions is used. Console proxies can be restarted by administrators but this will interrupt existing console sessions for users. +Creating an Instance Console Endpoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The access to an instance console is created by the API 'createConsoleEndpoint', +for the instance specified in the parameter 'virtualmachineid'. By default, +the CloudStack UI connects to the URL that this API generates. + +The response of the 'createConsoleEndpoint' API also contain the information +to create a websocket session to the VNC server on the console proxy, this +information includes: the host, port, path and token parameters required to +establish a websocket session, bypassing the VNC client on the console proxy. + +It is possible to add extra validation for the console proxy authentication, +with the following configurations: + +- ‘consoleproxy.extra.security.validation.enabled’: Enable/disable extra security + validation for console proxy using a token + +When ‘consoleproxy.extra.security.validation.enabled’ is true: then CloudStack +requests the ‘token’ parameter to the ‘createConsoleEndpoint’ API. The console URL +retrieved on the API response includes an ‘extra’ parameter for users validation on +the console proxy. + +When the console proxy receives a request including the ‘extra’ parameter it +will decode the ‘token’ parameter and uses the original token to compare it with +the ‘extra’ token. Only in case both matches, then the console access is allowed. + +When ‘consoleproxy.extra.security.validation.enabled’ is false: then CloudStack +does not require a token for validation. + +The websocket port is passed as a boot argument to the console proxy and the +management server decides between the secure or insecure port (8443 or 8080) when +setting the boot arguments for the CPVM. + +- The secure port 8443 is sent as a boot argument when: + + - The setting ‘consoleproxy.sslEnabled’ is true + + - The setting ‘consoleproxy.url.domain’ is not empty + + - There is a record on the ‘keystore’ database with name ‘CPVMCertificate’ + +- In any other case, then the port 8080 is selected + + +Administrators must ensure a new console proxy VM is recreated after changing +the value of any of the settings. Once the console proxy VM is recreated, +the new VNC server port will be used as the websocket traffic port. The console proxy +VM startup will also ensure a new iptable rule is added for the new VNC port, +allowing the traffic on it. + Using a SSL Certificate for the Console Proxy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -207,11 +312,11 @@ communication with SSL: - Set up a SSL wild-card certificate and domain name resolution -- Set up SSL certificate for specific FQDN and configure load-balancer +- Set up SSL certificate for specific FQDN and configure a load-balancer with optional ssl offloading. -Changing the Console Proxy SSL Certificate and Domain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Changing the Console Proxy SSL Certificate and Domains +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The administrator can configure SSL encryption by selecting a domain and uploading a new SSL certificate and private key. The domain must @@ -307,7 +412,7 @@ http://123.123.123.123:8080/client/api?command=uploadCustomCertificate&...&name= Here names are "root1" and "intermed1". If you used other names previously, please check the cloud.keystore table to obtain used names. -If you still have problems and folowing errors in management.log while destroying CPVM: +If you still have problems and following errors in management.log while destroying CPVM: - Unable to build keystore for CPVMCertificate due to CertificateException - Cold not find and construct a valid SSL certificate @@ -321,17 +426,46 @@ 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. -Load-balancing Console Proxies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Load-balancing Console Proxies / Secondary Storage VMs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An alternative to using dynamic DNS or creating a range of DNS entries as described in the last section would be to create a SSL certificate for a specific domain name, configure CloudStack to use that particular FQDN, and then configure a load balancer to load balance the console -proxy's IP address behind the FQDN. As the functionality for this is -still new, please see +proxy's IP address behind the FQDN. When using a load balancer it is +also possible to perform SSL-Offloading, so no certificate needs to be +configured on CloudStack itself. For further information please see https://cwiki.apache.org/confluence/display/CLOUDSTACK/Realhost+IP+changes for more details. +These ports needed to be configured for load-balancing: + +- 443 to 443 (to CPVM) +- 8080 to 8080 (to CPVM) +- 443 to 443 (to SSVM) + +SSL-Offloading with Load-balancing for Console Proxies / Secondary Storage VMs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To implement SSL-Offloading you need 2 public IP addresses (one for Console Proxy and one for Secondary Storage VM) which +each of them resolve to a different FQDN and terminate at the load balancer. Also 3 global settings need to be edited. + +- The setting ‘consoleproxy.url.domain’ to the FQDN used by the certificate (For example: cpvm.company.com) +- The setting ‘secstorage.ssl.cert.domain’ to the FQDN used by the certificate (For example: ssvm.company.com) +- The setting ‘secstorage.encrypt.copy’ to true + +.. warning:: + For sake of security you should block direct public access to the IP of Console Proxy and Secondary Storage VM. It is also + possible to add a fake public IP range to CloudStack which uses internal IP addresses for SystemVM use only. Please + be aware that the load balancer needs access to the used IP addresses to forward traffic. + +After edited global settings mentioned above you need to recreate both System VMs by destroying them. CloudStack will recreate +them with the new settings automatically. + +When using SSL-Offloading you need to configure following ports on the load balancer after adding the correct certificate to the public IP of each FQDN: + +- lb-publicip1:443 to CPVM:80 +- lb-publicip1:8080 to CPVM:8080 +- lb-publicip2:443 to SSVM:80 Virtual Router -------------- @@ -347,7 +481,7 @@ There is no mechanism for the administrator to log in to the virtual router. Virtual routers can be restarted by administrators, but this will interrupt public network access and other services for end users. A basic test in debugging networking issues is to attempt to ping the -virtual router from a guest VM. Some of the characteristics of the +virtual router from a Guest Instance. Some of the characteristics of the virtual router are determined by its associated system service offering. @@ -506,7 +640,7 @@ to the virtual router 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, +including schedule intervals, tests to skip, some configuration for LB, instances, Gateways, etc. 2. Basic and advanced tests as scheduled as per the intervals in the data sent @@ -527,7 +661,7 @@ fresh checks is expensive and will cause management server doing the following: 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. +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 @@ -559,7 +693,7 @@ This is achieved as follows: 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/' +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 @@ -573,55 +707,55 @@ 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. + 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 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. + 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 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 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) + 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. + 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. + (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. + % 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. + 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. @@ -644,7 +778,7 @@ Details of individual checks: 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 + 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. @@ -654,10 +788,10 @@ Details of individual checks: 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. + on the VR and instance 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. + '/etc/dhcphosts.txt' on the VR with the instance 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 @@ -704,7 +838,7 @@ it is upgraded: - SecurityGroup -- UserData +- User Data - DHCP @@ -740,7 +874,7 @@ Supported Virtual Routers Upgrading Virtual Routers ^^^^^^^^^^^^^^^^^^^^^^^^^ -#. Download the latest System VM template. +#. Download the latest System VM Template. #. Download the latest System VM to all the primary storage pools. @@ -754,7 +888,7 @@ Upgrading Virtual Routers # cloudstack-sysvmadm -d -u cloud -p -s Even when the VRs are still on older versions, existing services will - continue to be available to the VMs. The Management Server cannot + continue to be available to the instances. The Management Server cannot perform any operations on the VRs until they are upgraded. #. Selectively upgrade the VRs: @@ -797,12 +931,12 @@ In addition to the hosts, CloudStack’s Secondary Storage VM mounts and writes to secondary storage. Submissions to secondary storage go through the Secondary Storage VM. -The Secondary Storage VM can retrieve templates and ISO images from URLs +The Secondary Storage VM can retrieve Templates and ISO images from URLs using a variety of protocols. The secondary storage VM provides a background task that takes care of a -variety of secondary storage activities: downloading a new template to a -Zone, copying templates between Zones, and snapshot backups. +variety of secondary storage activities: downloading a new Template to a +Zone, copying Templates between Zones, and Snapshot backups. The administrator can log in to the secondary storage VM if needed. @@ -810,7 +944,7 @@ The administrator can log in to the secondary storage VM if needed. .. |update-ssl.png| image:: /_static/images/update-ssl.png :alt: Updating Console Proxy SSL Certificate .. |vr-upgrade.png| image:: /_static/images/vr-upgrade.png - :alt: Button to upgrade VR to use the new template. + :alt: Button to upgrade VR to use the new Template. Migrating System VMs -------------------- @@ -819,6 +953,62 @@ System VMs (any of the Console Proxy VM, Secondary Storage VM, Virtual Router or Since CloudStack 4.16, for VMware, migration of System VMs can also be done to a destination host in a different cluster belonging to the same pod (in case of cluster-wide primary storage pools, this will cause the Root volume of the system VM to be migrated to the appropriate datastore in the new cluster). Storage migration of stopped System VMs is also supported. +Customizing System VMs +---------------------- + +CloudStack supports User Data for System VMs at boot time. +The default root administrator can supply initialization scripts or configuration to automate tasks +such as installing additional packages, setting environment variables, or configuring telemetry. +Ensure that the User Data is valid for cloud-init. +Invalid content may prevent a System VM from functioning correctly. + +Initialization is performed by a CloudStack service, not by the systemd +cloud-init unit, to avoid conflicts with CloudStack System VM services. + +.. warning:: + User Data offers powerful customization, but inappropriate or intrusive scripts can + destabilize or break System VMs. Avoid modifying critical services or networking unless + you fully understand the impact, and always test changes in a non-production environment + before rollout. + +To enable and configure User Data for System VMs: + +#. Create a User Data entry under the default root administrator account. +#. Set the global setting ``systemvm.userdata.enabled`` to ``true``. +#. Provide the ID of the User Data per System VM type using the following global settings: + + .. cssclass:: table-striped table-bordered table-hover + ================================= ========================================================= + Global Setting Description + ================================= ========================================================= + ``console.proxy.vm.userdata`` ID of the User Data for Console Proxy VMs + ``secstorage.vm.userdata`` ID of the User Data for Secondary Storage VMs + ``virtual.router.userdata`` ID of the User Data for Virtual Routers, VPC VR, + internal LB Instances, and elastic LB Instances + ================================= ========================================================= + +#. Destroy the System VMs and allow CloudStack to re-deploy them to apply the changes. + +.. note:: + Only the default root administrator can set the global settings for System VM User Data. + The associated User Data entries must also be created under the default root administrator account. + +.. note:: + The size of the User Data that can be sent is dependent on the + hypervisor. This is because of the way it is provided to the system VM. + The user data is compressed and encoded in base64 format when it is + provided to the system VM along with other system VM configurations. + + - KVM: Uses QEMU Guest Agent to write configuration directly to + ``/var/cache/cloud/cmdline`` inside the VM + + - XenServer (HVM): Stores in XenStore key ``vm-data/cloudstack/init`` + + - VMware: Sets as ``machine.id`` extraConfig parameter + + The operator needs to ensure that the user data is within the limits + of the hypervisor. + Troubleshoot networks from System VMs ------------------------------------- .. |run-diagnostics-icon.png| image:: /_static/images/run-diagnostics-icon.png @@ -846,7 +1036,7 @@ The Extra Args parameter is for specifying command line optional parameters as one would when executing any of the tools from the terminal or command line. The supported versions are Debian 10 based since system VMs are built using the -same Debian 10 based templates. +same Debian 10 based Templates. | See: | Traceroute(1): https://manpages.debian.org/stretch/traceroute/traceroute.1.en.html @@ -950,4 +1140,4 @@ generated diagnostics data files and are as follows: Sets the secondary storage disk utilisation percentage for file retrieval. An exception is thrown when no secondary store is found with a lower capacity - than the specified value. The default value is 0.95 (95 %). \ No newline at end of file + than the specified value. The default value is 0.95 (95 %). diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst index e15272ab5a..2373fea198 100644 --- a/source/adminguide/templates.rst +++ b/source/adminguide/templates.rst @@ -16,79 +16,79 @@ 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. +A Template is a reusable configuration for Instances. When Users +launch Instances, they can choose from a list of Templates in CloudStack. -Specifically, a template is a virtual disk image that includes one of a +Specifically, a Template is a virtual disk image that includes one of a variety of operating systems, optional additional software such as office applications, and settings such as access control to determine -who can use the template. Each template is associated with a particular -type of hypervisor, which is specified when the template is added to +who can use the Template. Each Template is associated with a particular +type of hypervisor, which is specified when the Template is added to CloudStack. -CloudStack ships with a default template. In order to present more -choices to users, CloudStack administrators and users can create -templates and add them to CloudStack. +CloudStack ships with a default Template. In order to present more +choices to Users, CloudStack administrators and Users can create +Templates and add them to CloudStack. Creating Templates: Overview ---------------------------- -CloudStack ships with a default template for the CentOS operating -system. There are a variety of ways to add more templates. -Administrators and end users can add templates. The typical sequence of +CloudStack ships with a default Template for the CentOS operating +system. There are a variety of ways to add more Templates. +Administrators and end Users can add Templates. The typical sequence of events is: -#. Launch a VM instance that has the operating system you want. Make any - other desired configuration changes to the VM. +#. Launch an Instance that has the operating system you want. Make any + other desired configuration changes to the Instance. -#. Stop the VM. +#. Stop the Instance. -#. Convert the volume into a template. +#. Convert the volume into a Template. -There are other ways to add templates to CloudStack. For example, you -can take a snapshot of the VM's volume and create a template from the -snapshot, or import a VHD from another system into CloudStack. +There are other ways to add Templates to CloudStack. For example, you +can take a Snapshot of the Instance's volume and create a Template from the +Snapshot, or import a VHD from another system into CloudStack. -The various techniques for creating templates are described in the next +The various techniques for creating Templates are described in the next few sections. Requirements for Templates -------------------------- -- For XenServer, install PV drivers / Xen tools on each template that +- For XenServer, install PV drivers / Xen tools on each Template that you create. This will enable live migration and clean guest shutdown. -- For vSphere, install VMware Tools on each template that you create. +- For vSphere, install VMware Tools on each Template that you create. This will enable console view to work properly. Best Practices for Templates ---------------------------- -If you plan to use large templates (100 GB or larger), be sure you have -a 10-gigabit network to support the large templates. A slower network -can lead to timeouts and other errors when large templates are used. +If you plan to use large Templates (100 GB or larger), be sure you have +a 10-gigabit Network to support the large Templates. A slower Network +can lead to timeouts and other errors when large Templates are used. The Default Template -------------------- -CloudStack includes a CentOS template. This template is downloaded by +CloudStack includes a CentOS Template. This Template is downloaded by the Secondary Storage VM after the primary and secondary storage are -configured. You can use this template in your production deployment or -you can delete it and use custom templates. +configured. You can use this Template in your production deployment or +you can delete it and use custom Templates. -The root password for the default template is "password". +The root password for the default Template is "password". -A default template is provided for each of XenServer, KVM, and vSphere. -The templates that are downloaded depend on the hypervisor type that is -available in your cloud. Each template is approximately 2.5 GB physical +A default Template is provided for each of XenServer, KVM, and vSphere. +The Templates that are downloaded depend on the hypervisor type that is +available in your cloud. Each Template is approximately 2.5 GB physical size. -The default template includes the standard iptables rules, which will -block most access to the template excluding ssh. +The default Template includes the standard iptables rules, which will +block most access to the Template excluding ssh. .. code:: bash @@ -121,35 +121,35 @@ block most access to the template excluding ssh. Private and Public Templates ---------------------------- -When a user creates a template, it can be designated private or public. +When a User creates a Template, it can be designated private or public. -Private templates are only available to the user who created them. By -default, an uploaded template is private. +Private Templates are only available to the User who created them. By +default, an uploaded Template is private. -When a user marks a template as “public,” the template becomes available -to all users in all accounts in the user's domain, as well as users in -any other domains that have access to the Zone where the template is +When a User marks a Template as “public,” the Template becomes available +to all Users in all Accounts in the User's domain, as well as Users in +any other domains that have access to the Zone where the Template is stored. This depends on whether the Zone, in turn, was defined as private or public. A private Zone is assigned to a single domain, and a -public Zone is accessible to any domain. If a public template is created -in a private Zone, it is available only to users in the domain assigned -to that Zone. If a public template is created in a public Zone, it is -available to all users in all domains. +public Zone is accessible to any domain. If a public Template is created +in a private Zone, it is available only to Users in the domain assigned +to that Zone. If a public Template is created in a public Zone, it is +available to all Users in all domains. +.. _creating-a-template-from-an-existing-virtual-machine: +Creating a Template from an Existing Instance +--------------------------------------------- -Creating a Template from an Existing Virtual Machine ----------------------------------------------------- - -Once you have at least one VM set up in the way you want, you can use it -as the prototype for other VMs. +Once you have at least one Instance set up in the way you want, you can use it +as the prototype for other Instances. -#. Create and start a virtual machine using any of the techniques given - in `“Creating VMs” `_. +#. Create and start an Instance using any of the techniques given + in `“Creating Instances” `_. -#. Make any desired configuration changes on the running VM, then click +#. Make any desired configuration changes on the running Instance, then click Stop. -#. Wait for the VM to stop. When the status shows Stopped, go to the +#. Wait for the Instance to stop. When the status shows Stopped, go to the next step. #. Go into "View Volumes" and select the Volume having the type "ROOT". @@ -163,13 +163,13 @@ as the prototype for other VMs. certain operations and make assumptions that improve the performance of the guest. Select one of the following. - - If the operating system of the stopped VM is listed, choose it. + - If the operating system of the stopped Instance is listed, choose it. - - If the OS type of the stopped VM is not listed, choose Other. + - If the OS type of the stopped Instance is not listed, choose Other. - - If you want to boot from this template in PV mode, choose Other + - If you want to boot from this Template in PV mode, choose Other PV (32-bit) or Other PV (64-bit). This choice is available only - for XenServere: + for XenServer: .. note:: Generally you should not choose an older version of the OS @@ -178,35 +178,35 @@ as the prototype for other VMs. In those cases you should choose Other. - - **Public**. Choose Yes to make this template accessible to all - users of this CloudStack installation. The template will appear in + - **Public**. Choose Yes to make this Template accessible to all + Users of this CloudStack installation. The Template will appear in the Community Templates list. See `“Private and Public Templates” <#private-and-public-templates>`_. - - **Password Enabled**. Choose Yes if your template has the + - **Password Enabled**. Choose Yes if your Template has the CloudStack password change script installed. See :ref:`adding-password-management-to-templates`. #. Click Add. -The new template will be visible in the Templates section when the -template creation process has been completed. The template is then -available when creating a new VM. +The new Template will be visible in the Templates section when the +Template creation process has been completed. The Template is then +available when creating a new Instance. .. note:: - Since version 4.15, CloudStack obtains information from the VMware templates - automatically at registration time. If a template contains different deployment + Since version 4.15, CloudStack obtains information from the VMware Templates + automatically at registration time. If a Template contains different deployment options (or configurations) as in the case of virtual appliances, then CloudStack - display the information required by the template, allowing users or administrators - to configure their instances. + display the information required by the Template, allowing Users or administrators + to configure their Instances. Creating a Template from a Snapshot ----------------------------------- -If you do not want to stop the VM in order to use the Create Template +If you do not want to stop the Instance in order to use the Create Template menu item (as described in `“Creating a Template from an Existing -Virtual Machine” <#creating-a-template-from-an-existing-virtual-machine>`_), -you can create a template directly from any snapshot through the +Instance” <#creating-a-template-from-an-existing-virtual-machine>`_), +you can create a Template directly from any Snapshot through the CloudStack UI. @@ -218,15 +218,15 @@ Uploading Templates from a remote HTTP server vSphere Templates and ISOs ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. warning:: - If you are uploading a template that was created using vSphere Client, + If you are uploading a Template that was created using vSphere Client, be sure the OVA file does not contain an ISO. If it does, the deployment - of VMs from the template will fail + of Instances from the Template will fail Templates are uploaded based on a URL. HTTP is the supported access protocol. Templates are frequently large files. You can optionally gzip them to decrease upload times. -To upload a template: +To upload a Template: #. In the left navigation bar, click Templates. @@ -240,11 +240,11 @@ To upload a template: - **URL**. The Management Server will download the file from the specified URL, such as ``http://my.web.server/filename.vhd.gz``. - - **Zone**. Choose the zone where you want the template to be + - **Zone**. Choose the zone where you want the Template to be available, or All Zones to make it available throughout CloudStack. - - **Read VM settings from OVA**. (VMware only) If selected, the registered template will allow users to deploy VMs as clones of the template, including all their properties, configurations, end-user license agreements, disks, os type, etc. This option allows users to register virtual appliances. See `Support for Virtual Appliances `_. + - **Read Instance settings from OVA**. (VMware only) If selected, the registered Template will allow Users to deploy Instances as clones of the Template, including all their properties, configurations, end-user license agreements, disks, os type, etc. This option allows Users to register virtual appliances. See `Support for Virtual Appliances `_. .. note:: When this option is selected the following fields are hidden: Root disk controller, Keyboard type and OS Type. @@ -253,9 +253,9 @@ To upload a template: certain operations and make assumptions that improve the performance of the guest. Select one of the following: - - If the operating system of the stopped VM is listed, choose it. + - If the operating system of the stopped Instance is listed, choose it. - - If the OS type of the stopped VM is not listed, choose Other. + - If the OS type of the stopped Instance is not listed, choose Other. .. note:: You should not choose an older version of the OS than the @@ -264,35 +264,47 @@ To upload a template: those cases you should choose Other. .. note:: - Since version 4.15.1, VMware templates do not allow users or administrators - selecting an OS Type when registering a template if the option 'Read VM settings from OVA' is selected. In this case, the OS Type is - obtained from the template after it is registered. + Since version 4.15.1, VMware Templates do not allow Users or administrators + selecting an OS Type when registering a Template if the option 'Read Instance settings from OVA' is selected. In this case, the OS Type is + obtained from the Template after it is registered. + + - **Tag**: The tag for the template. This tag can be used with host tags to + allow deployment of Instances on specific hosts. + + - **User Data**: The registered User Data entries are listed. Select the + desired one. + + - **User Data link policy**: Select the User Data override policy as required. + For more information on User Data and override link policy, please check `User Data section `_. + - **Hypervisor**: The supported hypervisors are listed. Select the desired one. - - **Format**. The format of the template upload file, such as VHD or + - **Arch**: The supported arch types are listed. Select the desired one. + + - **Format**. The format of the Template upload file, such as VHD or OVA. - - **Extractable**. Choose Yes if the template is available for - extraction. If this option is selected, end users can download a - full image of a template. + - **Extractable**. Choose Yes if the Template is available for + extraction. If this option is selected, end Users can download a + full image of a Template. - - **Public**. Choose Yes to make this template accessible to all - users of this CloudStack installation. The template will appear in + - **Public**. Choose Yes to make this Template accessible to all + Users of this CloudStack installation. The Template will appear in the Community Templates list. See `“Private and Public Templates” <#private-and-public-templates>`_. - - **Featured**. Choose Yes if you would like this template to be - more prominent for users to select. The template will appear in + - **Featured**. Choose Yes if you would like this Template to be + more prominent for Users to select. The Template will appear in the Featured Templates list. Only an administrator can make a - template Featured. + Template Featured. -Note that uploading multi-disk templates is also supported. +Note that uploading multi-disk Templates is also supported. .. note:: - VMware only: If the template is registered with the option 'Read VM settings - from OVA' then the VM deployment wizard will display all the available OVF + VMware only: If the Template is registered with the option 'Read Instance settings + from OVA' then the Instance deployment wizard will display all the available OVF properties, different deployment options or configurations, multiple NICs or end-user license agreements. @@ -307,8 +319,8 @@ Note that uploading multi-disk templates is also supported. Uploading Templates and ISOs from a local computer ------------------------------------------- -It's also possible to upload an already prepared template or an ISO from your local computer. -The steps are similar as when Uploading a template/ISO from a remote HTTP server, except that you need to choose a local template/ISO file from your PC. +It's also possible to upload an already prepared Template or an ISO from your local computer. +The steps are similar as when Uploading a Template/ISO from a remote HTTP server, except that you need to choose a local Template/ISO file from your PC. For this feature to work, your SSVMs must be supporting HTTPS (for more info please visit `“Using a SSL Certificate for the Console Proxy” `_). @@ -318,68 +330,68 @@ Example GUI dialog of uploading Template/ISO from local (browser) is given below |upload-iso-from-local.png| -Note that uploading multi-disk templates is also supported. +Note that uploading multi-disk Templates is also supported as well as selecting the template/ISO arch type. -Sharing templates and ISOs with other accounts/projects ----------------------------------------------- +Sharing Templates and ISOs with other Accounts/projects +------------------------------------------------------- -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. +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 owners can share their template/ISO with: - - other accounts inside their own domain (i.e. can't share the template/ISO with other accounts in the subdomain of their domain or any other domains) +Currently, the owners can share their Template/ISO with: + - other Accounts inside their own domain (i.e. can't share the Template/ISO with other Accounts in the subdomain of their domain or any other domains) - projects where they belongs to (i.e. projects where they are the owners/creators or other projects where they have been joined) -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. +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/ISO, it is required to specify account/project name which is being added/removed from the template/ISO 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 the regular users (of a "User" role) wants to share a template/ISO via GUI, they will not be shown the list of all accounts in their domain and they will need to know the name of the destination account with which they are 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: +Global setting "allow.user.view.all.domain.accounts" has a default value of "false". This makes sure that when the regular Users (of a "User" role) wants to share a Template/ISO via GUI, they will not be shown the list of all Accounts in their domain and they will need to know the name of the destination Account with which they are 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. + The images displayed below refer to Template permissions, but the same applies for ISO permissions. |template-permissions-update-manually-1.png| -Sharing the template with account "user2" +Sharing the Template with Account "user2" |template-permissions-update-manually-2.png| -Revoking permissions from account "user2" +Revoking permissions from Account "user2" -But in environments where privacy within a domain is not an issue, setting "allow.user.view.all.domain.accounts" setting to "true" will make sure that the user, who is sharing the template, will be presented a more user-friendly multi-select list, listing all the accounts in their domain. This is shown in the images below; +But in environments where privacy within a domain is not an issue, setting "allow.user.view.all.domain.accounts" setting to "true" will make sure that the User, who is sharing the Template, will be presented a more User-friendly multi-select list, listing all the Accounts in their domain. This is shown in the images below; |template-permissions-update-1.png| -Sharing the template with just account "user8" +Sharing the Template with just Account "user8" |template-permissions-update-2.png| -Sharing template with 2 specific projects +Sharing Template with 2 specific projects |template-permissions-update-3.png| -Revoking permissions from account "user8" +Revoking permissions from Account "user8" |template-permissions-update-4.png| Revoking permissions from both projects previously added -Finally, template permissions can be reset: +Finally, Template permissions can be reset: |template-permissions-update-5.png| Resetting (removing all) permissions .. warning:: - Project-owned templates are not supported to be shared outside of + Project-owned Templates are not supported to be shared outside of the Project, and if attempted to do so, a proper error message is shown. Exporting Templates ------------------- -End users and Administrators may export templates from the CloudStack. -Navigate to the template in the UI and choose the Download function from +End Users and Administrators may export Templates from the CloudStack. +Navigate to the Template in the UI and choose the Download function from the Actions menu. .. include:: templates/_create_linux.rst @@ -396,50 +408,56 @@ the Actions menu. Deleting Templates ------------------ -Templates may be deleted. In general, when a template spans multiple +Templates may be deleted. However when the Templates are used the default +behaviour is to refuse deletion. In general, when a Template spans multiple Zones, only the copy that is selected for deletion will be deleted; the -same template in other Zones will not be deleted. The provided CentOS -template is an exception to this. If the provided CentOS template is +same Template in other Zones will not be deleted. The provided CentOS +Template is an exception to this. If the provided CentOS Template is deleted, it will be deleted from all Zones. -When templates are deleted, the VMs instantiated from them will continue -to run. However, new VMs cannot be created based on the deleted -template. +When Templates are deleted, the Instances instantiated from them will continue +to run. However, new Instances cannot be created based on the deleted +Template. + +As said, Cloudstack refuses to delete a template when VMs based on the +template exist. If this is the case, the parameter "forced" can be set +to "true" to delete the template anyways. These VMs can no longer be +reinstalled from that template, but will be unaffected otherwise. Working with ISOs =================== -CloudStack supports ISOs and their attachment to guest VMs. An ISO is a +CloudStack supports ISOs and their attachment to Guest Instances. 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. +upload their own ISOs and mount them on their Guest Instances. 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 +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 +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 +CloudStack allows a User to boot a Guest Instance off of an ISO image. Users +can also attach ISO images to Guest Instances. For example, this enables installing PV drivers into Windows. ISO images are not hypervisor-specific. - +.. _adding-an-iso: 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 +with Guest Instances, 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. +part of a Template. -#. Log in to the CloudStack UI as an administrator or end user. +#. Log in to the CloudStack UI as an administrator or end User. #. In the left navigation bar, click Templates. @@ -479,9 +497,9 @@ part of a template. - (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 + - (KVM only) If you choose an OS that is PV-enabled, the Instances 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 OS is not PV-enabled, the Instances will have an IDE root disk. The PV-enabled types are: - Fedora 13 @@ -523,12 +541,14 @@ part of a template. extraction. - **Public**: Choose Yes if this ISO should be available to other - users. + 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 + prominent for Users to select. The ISO will appear in the Featured ISOs list. Only an administrator can make an ISO Featured. + - **Arch**: The supported arch types are listed. Select the desired one. + #. Click OK. The Management Server will download the ISO. Depending on the size of @@ -542,12 +562,12 @@ part of a template. with it. -Attaching an ISO to a VM -------------------------- +Attaching an ISO to a Instance +------------------------------ #. In the left navigation, click Instances. -#. Choose the virtual machine you want to work with. +#. Choose the Instance you want to work with. #. Click the Attach ISO button. |iso.png| @@ -569,16 +589,18 @@ Attaching an ISO to a VM .. |template-upload-from-local.png| image:: /_static/images/template-upload-from-local.png :alt: Upload Template from local .. |template-permissions-update-manually-1.png| image:: /_static/images/template-permissions-update-manually-1.png - :alt: USharing template with account "user2" + :alt: USharing template with Account "user2" .. |template-permissions-update-manually-2.png| image:: /_static/images/template-permissions-update-manually-2.png - :alt: Revoking permissions from account "user2" + :alt: Revoking permissions from Account "user2" .. |template-permissions-update-1.png| image:: /_static/images/template-permissions-update-1.png - :alt: Sharing template with just account "user8" + :alt: Sharing template with just Account "user8" .. |template-permissions-update-2.png| image:: /_static/images/template-permissions-update-2.png :alt: Sharing template with 2 specific projects .. |template-permissions-update-3.png| image:: /_static/images/template-permissions-update-3.png - :alt: Revoking permissins from account "user8" + :alt: Revoking permissions from Account "user8" .. |template-permissions-update-4.png| image:: /_static/images/template-permissions-update-4.png - :alt: Revoking permsissons from both projects previously added + :alt: Revoking permissions from both projects previously added .. |template-permissions-update-5.png| image:: /_static/images/template-permissions-update-5.png - :alt: Reseting (removing all) permissions + :alt: Resetting (removing all) permissions +.. |iso.png| image:: /_static/images/iso-icon.png + :alt: depicts adding an iso image diff --git a/source/adminguide/templates/._create_linux.rst.swp b/source/adminguide/templates/._create_linux.rst.swp new file mode 100644 index 0000000000..a5e9a0d741 Binary files /dev/null and b/source/adminguide/templates/._create_linux.rst.swp differ diff --git a/source/adminguide/templates/_bypass-secondary-storage-kvm.rst b/source/adminguide/templates/_bypass-secondary-storage-kvm.rst index d45f0489df..080e5ef9a9 100644 --- a/source/adminguide/templates/_bypass-secondary-storage-kvm.rst +++ b/source/adminguide/templates/_bypass-secondary-storage-kvm.rst @@ -16,16 +16,16 @@ .. _bypass-secondary-storage-kvm: -Bypassing Secondary Storage For KVM templates +Bypassing Secondary Storage For KVM Templates --------------------------------------------- -CloudStack provides an additional way to register and use templates on KVM. +CloudStack provides an additional way to register and use Templates on KVM. -Instead of registering a template and storing it on secondary storage, the user can opt to skip downloading the template to secondary storage for KVM at template registration. At deployment time, the template is downloaded directly to primary storage from the registered source, instead of being copied from secondary storage. +Instead of registering a Template and storing it on secondary storage, the user can opt to skip downloading the Template to secondary storage for KVM at Template registration. At deployment time, the Template is downloaded directly to primary storage from the registered source, instead of being copied from secondary storage. -Supported protocols: HTTP/HTTPS, NFS and metalinks. The protocol is obtained from the template URL. +Supported protocols: HTTP/HTTPS, NFS and metalinks. The protocol is obtained from the Template URL. -To enable this option for a template: +To enable this option for a Template: #. In the left navigation bar, click Templates. @@ -37,11 +37,11 @@ To enable this option for a template: - **Direct Download**. This option will be shown in the UI when KVM is selected as the hypervisor. Choose Yes to enable the bypassing secondary storage option. - - **Checksum**. Optional field. If this field is populated, the checksum is compared to the downloaded template checksum when the template is downloaded to primary storage at deployment time. + - **Checksum**. Optional field. If this field is populated, the checksum is compared to the downloaded Template checksum when the Template is downloaded to primary storage at deployment time. -After the template is registered, it is automatically available for VM deployments. +After the Template is registered, it is automatically available for instance deployments. -From CloudStack 4.14.0, system VM templates also support direct download. An administrator can register a new system VM template as ROUTING or USER type with the direct download flag, and it can be changed to SYSTEM type during the upgrade or by out-of-band database changes. Type of newly registered template can be changed to SYSTEM in the database using a SQL query similar to: +From CloudStack 4.14.0, system VM Templates also support direct download. An administrator can register a new system VM Template as ROUTING or USER type with the direct download flag, and it can be changed to SYSTEM type during the upgrade or by out-of-band database changes. Type of newly registered Template can be changed to SYSTEM in the database using a SQL query similar to: .. code:: bash @@ -49,8 +49,9 @@ From CloudStack 4.14.0, system VM templates also support direct download. An adm Uploading Certificates for Direct Downloads -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For direct downloads over HTTPS, the KVM hosts must have valid certificates. These certificates can be either self-signed or signed and will allow the KVM hosts to access the templates/ISOs and download them. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For direct downloads over HTTPS, the KVM hosts must have valid certificates. These certificates can be either self-signed or signed and will allow the KVM hosts to access the Templates/ISOs and download them. CloudStack provides some APIs to handle certificates for direct downloads: @@ -84,8 +85,8 @@ CloudStack provides some APIs to handle certificates for direct downloads: upload templatedirectdownloadcertificate hypervisor=KVM name=CERTIFICATE_ALIAS zoneid=ZONE_ID certificate=CERTIFICATE_FORMATTED hostid=HOST_ID -Syncronising Certificates for Direct Downloads -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Synchronising Certificates for Direct Downloads +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As new hosts may be added to a zone which do not include a certificate which was previously uploaded to pre-existing hosts. @@ -97,9 +98,9 @@ CloudStack provides a way to synchronize certificates across all the connected h - Upload missing certificates to hosts Direct Download Timeouts -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ -With 4.14.0, ability to configure different timeout values for the direct downloading of templates has been added. Three new global settings have been added for this: +With 4.14.0, ability to configure different timeout values for the direct downloading of Templates has been added. Three new global settings have been added for this: - **direct.download.connect.timeout** - Connection establishment timeout in milliseconds for direct download. Default value: 5000 milliseconds. diff --git a/source/adminguide/templates/_cloud_init.rst b/source/adminguide/templates/_cloud_init.rst new file mode 100644 index 0000000000..93413e6dc1 --- /dev/null +++ b/source/adminguide/templates/_cloud_init.rst @@ -0,0 +1,255 @@ +.. 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. + + +Cloud-init integration +------------------------- + +Cloudstack and cloud-init integration provide Instances with advanced management features such as: + +* Password management +* SSH keys management +* Partition management +* User Data input +* `Other modules `_ + + + +Examples for relevant features are listed for different distributions. + +~~~~~~~~~~~~~~~~~~~~~~ + +Linux with Cloud-init +---------------------- + +These features can be implemented in `“Linux Template creation process” <_create_linux.html#creating-a-linux-template>`_. where they are executed just before the **Template cleanup** step. + +#. **Install and configure cloud-init** + + Install cloud-init and mentioned auxiliary packages. + + ~ CentOS + + .. code:: bash + + yum install -y cloud-init wget + + ~ Ubuntu + + .. code:: bash + + apt-get install -y cloud-init wget + + Configure cloud-init to detect Cloudstack data source during runtime. + + Cloud-init data sources can be specified in /etc/cloud/cloud.cfg.d/ directory. Add the following config in /etc/cloud/cloud.cfg.d/99_cloudstack.cfg. + + .. code:: bash + + datasource_list: [ ConfigDrive, CloudStack, None ] + datasource: + CloudStack: {} + None: {} + + .. note:: + For the vm instances running on VMware or XenServer/XCP-ng hypervisors, if there are multiple cloud-init data sources, it is a known issue that ds-identify is not able to detect if "CloudStack" DataSource is enabled. To fix the problem, please run the following command to enable cloud-init without any aid from ds-identify. + + .. code:: bash + + echo "policy: enabled" > /etc/cloud/ds-identify.cfg + +#. **Password management** + + Cloudstack integration with cloud-init `set-passwords module `_ will enable the platform to set a password for each Instance created from the Main Template. Additionally it will allow to reset the user password through the GUI. + + - **Enable set_passwords module on every boot** + + By default the set-passwords module runs only on first boot of the Instance, change that to run on every boot. + + .. code:: bash + + sudo sed -i s/" - set[_|-]passwords"/" - [set_passwords, always]"/g /etc/cloud/cloud.cfg + + - **Specify the managed user** + + Cloudstack will create the user, set a password and reset it when requested. To do that set the following configuration in /etc/cloud/cloud.cfg.d/80_user.cfg + + .. code:: bash + + system_info: + default_user: + name: cloud-user + lock_passwd: false # disable user password login - true/false + sudo: [\"ALL=(ALL) ALL\"] # User permissions + disable_root: 0 # root remote login is 0 - enabled, 1 - disabled + ssh_pwauth: 1 # password login is 0 - disabled, 1- enabled + +#. **SSH keys management** + + Cloud-init `ssh module `_ can automatically install new SSH keys when set or reset from Cloudstack GUI. + By default the module runs once during Instance creation and will fetch Cloudstack keys without any additional configuration. + To enable Cloudstack reset SSH keys feature configure cloud-init ssh module to run on every boot. + + .. code:: bash + + sudo sed -i s/" - ssh$"/" - [ssh, always]"/g /etc/cloud/cloud.cfg + +======= + + .. warning:: + + If the cloud-init ssh module is set to run every boot, it will regenerate the certificate fingerprint of the host. This will cause a warning to anyone that logs in the system and also bring trouble to anyone trying to automate ssh access. + + Disable cloud-init regenerating host certificates on boot. If Template certificates are deleted they will be regenerated by the OS on instance first boot. + + .. code:: bash + + echo "ssh_deletekeys: false" > /etc/cloud/cloud.cfg.d/49_hostkeys.cfg + + Note that if this instance is moved or snapshotted, it will be vulnerable to man-in-the-middle attacks if the behavior is not re-enabled first. + +#. **Partition management** + + Cloud-init can detect and resize one or more existing partitions automatically after reboot. This guide will cover root partition and volume. + First install the `Growpart module `_ as it is not shipped with cloud-init. + + ~ Centos + + .. code:: bash + + yum install cloud-utils-growpart -y + + ~ Ubuntu + + .. code:: bash + + apt-get install cloud-initramfs-growroot -y + + - **Detect and extend MBR partitions** + + Locate the root partition. + + .. note:: + + Root partition can differ per OS type, version and partition setup. + + .. code:: bash + + [root@localhost ~]# lvs + LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert + root centos -wi-ao---- <17.00g + swap centos -wi-ao---- 2.00g + [root@localhost ~]# vgs + VG #PV #LV #SN Attr VSize VFree + centos 1 2 0 wz--n- <19.00g 0 + [root@localhost ~]# pvs + PV VG Fmt Attr PSize PFree + /dev/xvda2 centos lvm2 a-- <19.00g 0 + + On the current setup root is on /dev/xvda2 partition. Define the configuration below in /etc/cloud/cloud.cfg.d/50_growpartion.cfg + + .. code:: bash + + growpart: + mode: auto + devices: + - \"/dev/xvda2\" + ignore_growroot_disabled: false + + Now on every boot growpart will check and extend /dev/xvda2 if there is change in size. + + - **Extend Physical volume, Volume group and root lvm** + + After partition is extended the upper layers should also be resized. This can be automated with cloud-init `runcmd module `_ . Set the configuration below in /etc/cloud/cloud.cfg.d/51_extend_volume.cfg. + + ~ CentOS + + CentOS root volume is /dev/centos/root if no changes are done during installation. Change the value accordingly if setup is different. + + .. code:: bash + + runcmd: + - [ cloud-init-per, always, grow_VG, pvresize, /dev/xvda2 ] + - [ cloud-init-per, always, grow_LV, lvresize, -l, '+100%FREE', /dev/centos/root ] + - [ cloud-init-per, always, grow_FS, xfs_growfs, /dev/centos/root ] + + ~ Ubuntu + + Ubuntu 20 root volume is /dev/ubuntu-vg/ubuntu-lv if no changes are done during installation. Change the value accordingly if setup is different. + + .. code:: bash + + runcmd: + - [ cloud-init-per, always, grow_VG, pvresize, /dev/xvda3 ] + - [ cloud-init-per, always, grow_LV, lvresize, -l, '+100%FREE', /dev/ubuntu-vg/ubuntu-lv ] + - [ cloud-init-per, always, grow_FS, xfs_growfs, /dev/ubuntu-vg/ubuntu-lv ] + + .. warning:: + + The example code above is based on XFS partition type. If ext4 partitioning is utilized replace **xfs_growfs** with **resize2fs** in the last code line. + It is possible to also use cloud-init `resize2fs module `_ . + + - **Enable autoresize on every boot** + + By default cloud-init **runcmd** module executes defined commands on first boot only. + Commands will run on every boot only if both **runcmd** and **user-scripts** modules are configured to run on every boot. + + .. code:: bash + + sudo sed -i s/" - runcmd"/" - [runcmd, always]"/g /etc/cloud/cloud.cfg + sudo sed -i s/" - scripts-user"/" - [scripts-user, always]"/g /etc/cloud/cloud.cfg + +#. **User Data** + + Cloud-init can parse and execute User Data form Cloud-stack during Instance creation. This feature works as is without additional configuration. + +#. **Network configuration with ConfigDrive** + + Cloud-init can fetch network configuration from ConfigDrive. To enable this, + ensure network configuration is not disabled in cloud-init configuration. + + .. code:: bash + + echo -e "\nnetwork: {}" >> /etc/cloud/cloud.cfg + + .. note:: + Adding/removing nic to/from an instance or updating the ip address of a nic + will not be reflected in the instance if the instance is already running. To + do so, run `cloud-init clean --machine-id -s` to clean the machine id and + seed data. Then reboot the instance to apply the changes. + +#. **Cleanup** + + Once desired cloud-init features are implemented, clean cloud-init tracker files. + + .. code:: bash + + cloud-init clean + + Or do it manually. + + .. code:: bash + + rm -rf /var/lib/cloud/* + + If **Password management** feature is used clean /etc/sudoers from any cloud-init user setups. + + .. code:: bash + + rm -rf /etc/sudoers.d/* + +#. **Finalize Template** + + Proceed with `“Linux Template creation process” <_create_linux.html>`_ continuing with **Template cleanup** step. diff --git a/source/adminguide/templates/_convert_hyperv.rst b/source/adminguide/templates/_convert_hyperv.rst index 9e15490ddd..620d1ea200 100644 --- a/source/adminguide/templates/_convert_hyperv.rst +++ b/source/adminguide/templates/_convert_hyperv.rst @@ -1,15 +1,15 @@ -Converting a Hyper-V VM to a Template -------------------------------------- +Converting a Hyper-V Instance to a Template +------------------------------------------- -To convert a Hyper-V VM to a XenServer-compatible CloudStack template, +To convert a Hyper-V Instance to a XenServer-compatible CloudStack Template, you will need a standalone XenServer host with an attached NFS VHD SR. Use whatever XenServer version you are using with CloudStack, but use XenCenter 5.6 FP1 or SP2 (it is backwards compatible to 5.6). Additionally, it may help to have an attached NFS ISO SR. -For Linux VMs, you may need to do some preparation in Hyper-V before -trying to get the VM to work in XenServer. Clone the VM and work on the -clone if you still want to use the VM in Hyper-V. Uninstall Hyper-V +For Linux Instances, you may need to do some preparation in Hyper-V before +trying to get the Instance to work in XenServer. Clone the Instance and work on the +clone if you still want to use the Instance in Hyper-V. Uninstall Hyper-V Integration Components and check for any references to device names in /etc/fstab: @@ -26,7 +26,7 @@ Integration Components and check for any references to device names in those entries (if any) to mount by LABEL or UUID. You can get that information with the blkid command. -The next step is make sure the VM is not running in Hyper-V, then get +The next step is make sure the Instance is not running in Hyper-V, then get the VHD into XenServer. There are two options for doing this. Option one: @@ -36,10 +36,10 @@ Option one: #. Choose the VHD, then click Next. -#. Name the VM, choose the NFS VHD SR under Storage, enable "Run +#. Name the Instance, choose the NFS VHD SR under Storage, enable "Run Operating System Fixups" and choose the NFS ISO SR. -#. Click Next, then Finish. A VM should be created. +#. Click Next, then Finish. An Instance should be created. Option two: @@ -50,30 +50,30 @@ Option two: #. Input the XenServer host info, then click Next. -#. Name the VM, then click Next, then Convert. A VM should be created. +#. Name the Instance, then click Next, then Convert. An Instance should be created. -Once you have a VM created from the Hyper-V VHD, prepare it using the +Once you have an Instance created from the Hyper-V VHD, prepare it using the following steps: -#. Boot the VM, uninstall Hyper-V Integration Services, and reboot. +#. Boot the Instance, uninstall Hyper-V Integration Services, and reboot. #. Install XenServer Tools, then reboot. -#. Prepare the VM as desired. For example, run sysprep on Windows VMs. +#. Prepare the Instance as desired. For example, run sysprep on Windows Instances. See `“Creating a Windows Template” <#creating-a-windows-template>`_. -Either option above will create a VM in HVM mode. This is fine for -Windows VMs, but Linux VMs may not perform optimally. Converting a Linux -VM to PV mode will require additional steps and will vary by +Either option above will create an Instance in HVM mode. This is fine for +Windows Instances, but Linux Instances may not perform optimally. Converting a Linux +instance to PV mode will require additional steps and will vary by distribution. -#. Shut down the VM and copy the VHD from the NFS storage to a web +#. Shut down the instance and copy the VHD from the NFS storage to a web server; for example, mount the NFS share on the web server and copy it, or from the XenServer host use sftp or scp to upload it to the web server. -#. In CloudStack, create a new template using the following values: +#. In CloudStack, create a new Template using the following values: - URL. Give the URL for the VHD @@ -85,4 +85,4 @@ distribution. - Format. VHD -The template will be created, and you can create instances from it. +The Template will be created, and you can create instances from it. diff --git a/source/adminguide/templates/_create_linux.rst b/source/adminguide/templates/_create_linux.rst index 217556f398..d53a7b9b34 100644 --- a/source/adminguide/templates/_create_linux.rst +++ b/source/adminguide/templates/_create_linux.rst @@ -17,245 +17,199 @@ Creating a Linux Template ------------------------- -Linux templates should be prepared using this documentation in order to -prepare your linux VMs for template deployment. For ease of -documentation, the VM which you are configuring the template on will be -referred to as "Template Primary". This guide currently covers legacy -setups which do not take advantage of UserData and cloud-init and -assumes openssh-server is installed during installation. +Linux Templates should be prepared using this documentation in order to +prepare your linux Instances for Template deployment. For ease of +documentation, the Instance which you are configuring the Template on will be +referred to as "Main Template". The final product, as created and usable +for deployment in Cloudstack, will be referred as "Final Template". +This guide will cover cloud-init setup and scripted setups where available. It is assumed that openssh-server +is installed during installation. An overview of the procedure is as follow: #. Upload your Linux ISO. - For more information, see `“Adding an - ISO” `_. + For more information, see :ref:`adding-an-iso`. -#. Create a VM Instance with this ISO. +#. Create an Instance with this ISO. For more information, see `“Creating - VMs” `_. + Instances” `_. -#. Prepare the Linux VM +#. Prepare the Linux Instance -#. Create a template from the VM. +#. Create a Template from the Instance. For more information, see `“Creating a Template from an Existing - Virtual Machine” <#creating-a-template-from-an-existing-virtual-machine>`_. + Instance” <#creating-a-template-from-an-existing-instance>`_. System preparation for Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- + +The following steps will provide basic Linux installation for +templating of Centos and Ubuntu. + +#. **Update OS** + + The next step update the packages on the Main Template. + + ~ CentOS + + .. code:: bash + + yum update -y + reboot + + ~ Ubuntu + + .. code:: bash + + sudo -i + apt-get update + apt-get upgrade -y + apt-get install -y acpid ntp + reboot + +#. **Networking** + + Set Template Network interface configuration to DHCP so Cloudstack infrastructure can assign one on boot. + + .. warning:: + + For CentOS, it is mandatory to take unique identification out of the + interface configuration file /etc/sysconfig/network-scripts/ifcfg-eth0. Any entries starting with should be removed. + + ~ Centos + + .. code:: bash + + echo "DEVICE=eth0 + TYPE=Ethernet + BOOTPROTO=dhcp + ONBOOT=yes" > /etc/sysconfig/network-scripts/ifcfg-eth0 -The following steps will prepare a basic Linux installation for -templating. - -#. **Installation** +#. **Hostname Management** - It is good practice to name your VM something generic during - installation, this will ensure components such as LVM do not appear - unique to a machine. It is recommended that the name of "localhost" - is used for installation. - - .. warning:: - For CentOS, it is necessary to take unique identification out of the - interface configuration file, for this edit - /etc/sysconfig/network-scripts/ifcfg-eth0 and change the content to - the following. + Set a generic name to the Template Instance during installation, this will ensure components such as LVM do not appear unique to a machine. It is recommended that the name of "localhost" is used for installation. .. code:: bash - DEVICE=eth0 - TYPE=Ethernet - BOOTPROTO=dhcp - ONBOOT=yes - - The next steps updates the packages on the Template Primary. - - - Ubuntu - - .. code:: bash - - sudo -i - apt-get update - apt-get upgrade -y - apt-get install -y acpid ntp - reboot - - - CentOS - - .. code:: bash - - ifup eth0 - yum update -y - reboot + hostname localhost + echo "localhost" > /etc/hostname #. **Password management** - + .. note:: - If preferred, custom users (such as ones created during the Ubuntu - installation) should be removed. First ensure the root user account - is enabled by giving it a password and then login as root to continue. - - .. code:: bash - - sudo passwd root - logout + + It is a good practice to remove any non root Users that come with the OS (such as ones created during the Ubuntu + installation). First ensure the root user Account is enabled by giving it a password and then login as root to continue. - As root, remove any custom user accounts created during the - installation process. + Once logged in as root, any custom User can be removed. .. code:: bash - deluser myuser --remove-home - - See :ref:`adding-password-management-to-templates` for - instructions to setup the password management script, this will allow - CloudStack to change your root password from the web interface. - -#. **Hostname Management** - - CentOS configures the hostname by default on boot. Unfortunately - Ubuntu does not have this functionality, for Ubuntu installations use - the following steps. - - - Ubuntu - - The hostname of a Templated VM is set by a custom script in - `/etc/dhcp/dhclient-exit-hooks.d`, this script first checks if the - current hostname is localhost, if true, it will get the host-name, - domain-name and fixed-ip from the DHCP lease file and use those - values to set the hostname and append the `/etc/hosts` file for - local hostname resolution. Once this script, or a user has changed - the hostname from localhost, it will no longer adjust system files - regardless of its new hostname. The script also recreates - openssh-server keys, which should have been deleted before - templating (shown below). Save the following script to - `/etc/dhcp/dhclient-exit-hooks.d/sethostname`, and adjust the - permissions. - - .. code:: bash - - #!/bin/sh - # dhclient change hostname script for Ubuntu - oldhostname=$(hostname -s) - if [ $oldhostname = 'localhost' ] - then - sleep 10 # Wait for configuration to be written to disk - hostname=$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /host-name/ { host = $3 } END { printf host } ' | sed 's/[";]//g' ) - fqdn="$hostname.$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /domain-name/ { domain = $3 } END { printf domain } ' | sed 's/[";]//g')" - ip=$(cat /var/lib/dhcp/dhclient.eth0.leases | awk ' /fixed-address/ { lease = $2 } END { printf lease } ' | sed 's/[";]//g') - echo "cloudstack-hostname: Hostname _localhost_ detected. Changing hostname and adding hosts." - printf " Hostname: $hostname\n FQDN: $fqdn\n IP: $ip" - # Update /etc/hosts - awk -v i="$ip" -v f="$fqdn" -v h="$hostname" "/^127/{x=1} !/^127/ && x { x=0; print i,f,h; } { print $0; }" /etc/hosts > /etc/hosts.dhcp.tmp - mv /etc/hosts /etc/hosts.dhcp.bak - mv /etc/hosts.dhcp.tmp /etc/hosts - # Rename Host - echo $hostname > /etc/hostname - hostname -b -F /etc/hostname - echo $hostname > /proc/sys/kernel/hostname - # Recreate SSH2 - export DEBIAN_FRONTEND=noninteractive - dpkg-reconfigure openssh-server - fi - ### End of Script ### - - chmod 774 /etc/dhcp/dhclient-exit-hooks.d/sethostname - + deluser myuser --remove-home + + User password management and reset capabilities in GUI are available with: + + * `Cloud-init integration `_ + * `Adding Password Management to Your Templates `_ /Legacy for non systemd systems only/ + +#. **SSH keys management** + + Cloudstack can create key pair and push certificates to Instances. This feature is available with: + + * `Cloud-init integration `_ + * `Implementing a SSH-Key bash script `_ + +#. **Partition management** + + Volumes can autorextend after reboot when partition is extended in the GUI. + This feature is possible with `Cloud-init integration `_. + +#. **User Data** + + Cloudstack can push User Data during Instance creation. + This feature is possible with `Cloud-init integration `_. + +#. **Template cleanup** + .. warning:: - The following steps should be run when you are ready to template - your Template Primary. If the Template Primary is rebooted during - these steps you will have to run all the steps again. At the end - of this process the Template Primary should be shutdown and the - template created in order to create and deploy the final template. - -#. **Remove the udev persistent device rules** - - This step removes information unique to your Template Primary such as - network MAC addresses, lease files and CD block devices, the files - are automatically generated on next boot. - - - Ubuntu + + Cleanup steps should be run when all Main Template configuration + is done and just before the shutdown step. After shut down Final + Template should be created. If the Main Template is started or + rebooted before Final Template creation all cleanup steps have to be rerun. + + - **Remove the udev persistent device rules** + + This step removes information unique to the Main Template such as + Network MAC addresses, lease files and CD block devices, the files + are automatically generated on next boot. + + ~ CentOS .. code:: bash - rm -f /etc/udev/rules.d/70* - rm -f /var/lib/dhcp/dhclient.* - - - CentOS + rm -f /etc/udev/rules.d/70* + rm -f /var/lib/dhclient/* + + ~ Ubuntu .. code:: bash - rm -f /etc/udev/rules.d/70* - rm -f /var/lib/dhclient/* + rm -f /etc/udev/rules.d/70* + rm -f /var/lib/dhcp/dhclient.* -#. **Remove SSH Keys** + - **Remove SSH Keys** - This step is to ensure all your Templated VMs do not have the same - SSH keys, which would decrease the security of the machines - dramatically. + This step is to ensure all Templated Instances do not have the same + SSH keys, which would decrease the security of the machines + dramatically. - .. code:: bash + .. code:: bash rm -f /etc/ssh/*key* -#. **Cleaning log files** + - **Cleaning log files** - It is good practice to remove old logs from the Template Primary. + It is good practice to remove old logs from the Main Template. - .. code:: bash + .. code:: bash cat /dev/null > /var/log/audit/audit.log 2>/dev/null cat /dev/null > /var/log/wtmp 2>/dev/null logrotate -f /etc/logrotate.conf 2>/dev/null rm -f /var/log/*-* /var/log/*.gz 2>/dev/null -#. **Setting hostname** - - In order for the Ubuntu DHCP script to function and the CentOS - dhclient to set the VM hostname they both require the Template - Primary's hostname to be "localhost", run the following commands to - change the hostname. - - .. code:: bash - - hostname localhost - echo "localhost" > /etc/hostname + - **Set User password to expire** -#. **Set user password to expire** + This step forces the User to change the password of the Instance after the + Template has been deployed. - This step forces the user to change the password of the VM after the - template has been deployed. - - .. code:: bash + .. code:: bash passwd --expire root -#. **Clearing User History** + - **Clearing User History** - The next step clears the bash commands you have just run. + The next step clears the bash commands you have just run. - .. code:: bash + .. code:: bash history -c unset HISTFILE -#. **Shutdown the VM** +#. **Shutdown the Instance** - Your now ready to shutdown your Template Primary and create a - template! + Shutdown the Main Template. .. code:: bash halt -p -#. **Create the template!** - - You are now ready to create the template, for more information see - `“Creating a Template from an Existing Virtual - Machine” <#creating-a-template-from-an-existing-virtual-machine>`_. +#. **Create the Template!** -.. note:: - Templated VMs for both Ubuntu and CentOS may require a reboot after - provisioning in order to pickup the hostname. + You are now ready to create the Final Template, for more information see + :ref:`creating-a-template-from-an-existing-virtual-machine`. diff --git a/source/adminguide/templates/_create_windows.rst b/source/adminguide/templates/_create_windows.rst index cb1d5545ae..ae63f61b13 100644 --- a/source/adminguide/templates/_create_windows.rst +++ b/source/adminguide/templates/_create_windows.rst @@ -17,13 +17,13 @@ Creating a Windows Template --------------------------- -Windows templates must be prepared with Sysprep before they can be +Windows Templates must be prepared with Sysprep before they can be provisioned on multiple machines. Sysprep allows you to create a generic -Windows template and avoid any possible SID conflicts. +Windows Template and avoid any possible SID conflicts. .. note:: - (XenServer) Windows VMs running on XenServer require PV drivers, which - may be provided in the template or added after the VM is created. The + (XenServer) Windows instances running on XenServer require PV drivers, which + may be provided in the Template or added after the instance is created. The PV drivers are necessary for essential management functions such as mounting additional volumes and ISO images, live migration, and graceful shutdown. @@ -32,24 +32,28 @@ An overview of the procedure is as follows: #. Upload your Windows ISO. - For more information, see `“Adding an - ISO” `_. + For more information, see :ref:`adding-an-iso`. -#. Create a VM Instance with this ISO. +#. Create an instance with this ISO. For more information, see `“Creating - VMs” `_. + instances” <../virtual_machines.html#creating-instances>`_. + +#. Add Virtual TPM device to the instance. + + For more information, see `“Instance Settings for Virtual Trusted Platform Module (vTPM) + ” <../virtual_machines.html#instance-settings-for-virtual-trusted-platform-module-vtpm>`_. #. Follow the steps in Sysprep for Windows Server 2008 R2 (below) or Sysprep for Windows Server 2003 R2, depending on your version of Windows Server #. The preparation steps are complete. Now you can actually create the - template as described in Creating the Windows Template. + Template as described in Creating the Windows Template. System Preparation for Windows Server 2008 R2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For Windows 2008 R2, you run Windows System Image Manager to create a custom sysprep response XML file. Windows System Image Manager is @@ -68,8 +72,8 @@ Use the following steps to run sysprep for Windows 2008 R2: #. Download and install the Windows AIK .. note:: - Windows AIK should not be installed on the Windows 2008 R2 VM you - just created. Windows AIK should not be part of the template you + Windows AIK should not be installed on the Windows 2008 R2 instance you + just created. Windows AIK should not be part of the Template you create. It is only used to create the sysprep answer file. #. Copy the install.wim file in the \\sources directory of the Windows @@ -116,7 +120,7 @@ Use the following steps to run sysprep for Windows 2008 R2: |software-license.png| #. Make sure the license key is properly set. If you use MAK key, you - can just enter the MAK key on the Windows 2008 R2 VM. You need not + can just enter the MAK key on the Windows 2008 R2 instance. You need not input the MAK into the Windows System Image Manager. If you use KMS host for activation you need not enter the Product Key. Details of Windows Volume Activation can be found at @@ -140,7 +144,7 @@ Use the following steps to run sysprep for Windows 2008 R2: messages that appear in the validation window. #. Copy the unattend.xml file into the c:\\windows\\system32\\sysprep - directory of the Windows 2008 R2 Virtual Machine + directory of the Windows 2008 R2 Instance #. Once you place the unattend.xml file in c:\\windows\\system32\\sysprep directory, you run the sysprep tool as @@ -151,19 +155,19 @@ Use the following steps to run sysprep for Windows 2008 R2: cd c:\Windows\System32\sysprep sysprep.exe /oobe /generalize /shutdown - The Windows 2008 R2 VM will automatically shut down after sysprep is + The Windows 2008 R2 instance will automatically shut down after sysprep is complete. System Preparation for Windows Server 2003 R2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Earlier versions of Windows have a different sysprep tool. Follow these steps for Windows Server 2003 R2. #. Extract the content of \\support\\tools\\deploy.cab on the Windows installation CD into a directory called c:\\sysprep on the Windows - 2003 R2 VM. + 2003 R2 instance. #. Run c:\\sysprep\\setupmgr.exe to create the sysprep.inf file. diff --git a/source/adminguide/templates/_import_ami.rst b/source/adminguide/templates/_import_ami.rst index b81829fa8a..055d9fe937 100644 --- a/source/adminguide/templates/_import_ami.rst +++ b/source/adminguide/templates/_import_ami.rst @@ -102,14 +102,14 @@ To import an AMI: none /sys sysfs defaults 0 0 #. Enable login via the console. The default console device in a - XenServer system is xvc0. Ensure that etc/inittab and etc/securetty + XenServer system is xvc0. Ensure that etc/inittab and etc/security have the following lines respectively: .. code:: bash # grep xvc0 etc/inittab co:2345:respawn:/sbin/agetty xvc0 9600 vt100-nav - # grep xvc0 etc/securetty + # grep xvc0 etc/security xvc0 #. Ensure the ramdisk supports PV disk and PV network. Customize this @@ -147,7 +147,7 @@ To import an AMI: PermitRootLogin yes PasswordAuthentication yes -#. If you need the template to be enabled to reset passwords from the +#. If you need the Template to be enabled to reset passwords from the CloudStack UI or API, install the password change script into the image at this point. See :ref:`adding-password-management-to-templates`. diff --git a/source/adminguide/templates/_password.rst b/source/adminguide/templates/_password.rst index 1b39ae9739..4b62b372ec 100644 --- a/source/adminguide/templates/_password.rst +++ b/source/adminguide/templates/_password.rst @@ -24,25 +24,25 @@ to set a temporary admin or root password as well as reset the existing admin or root password from the CloudStack UI. To enable the Reset Password feature, you will need to download an -additional script to patch your template. When you later upload the -template into CloudStack, you can specify whether reset admin/root -password feature should be enabled for this template. +additional script to patch your Template. When you later upload the +Template into CloudStack, you can specify whether reset admin/root +password feature should be enabled for this Template. The password management feature works always resets the account password -on instance boot. The script does an HTTP call to the virtual router to +on Instance boot. The script does an HTTP call to the virtual router to retrieve the account password that should be set. As long as the virtual router is accessible the guest will have access to the account password that should be used. When the user requests a password reset the management server generates and sends a new password to the virtual -router for the account. Thus an instance reboot is necessary to effect +router for the account. Thus an Instance reboot is necessary to effect any password changes. -If the script is unable to contact the virtual router during instance +If the script is unable to contact the virtual router during Instance boot it will not set the password but boot will continue normally. Linux OS Installation -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ Use the following steps to begin the Linux OS installation: @@ -78,8 +78,8 @@ Use the following steps to begin the Linux OS installation: Windows OS Installation -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ Download the installer, CloudInstanceManager.msi, from the `Download page `_ -and run the installer in the newly created Windows VM. +and run the installer in the newly created Windows Instance. diff --git a/source/adminguide/troubleshooting.rst b/source/adminguide/troubleshooting.rst index f4c0efceb1..20d6d6a870 100644 --- a/source/adminguide/troubleshooting.rst +++ b/source/adminguide/troubleshooting.rst @@ -155,52 +155,52 @@ Solution Use vCenter to place the host in maintenance mode. -Unable to deploy VMs from uploaded vSphere template ---------------------------------------------------- +Unable to deploy Instances from uploaded vSphere Template +--------------------------------------------------------- Symptom ~~~~~~~~ -When attempting to create a VM, the VM will not deploy. +When attempting to create an Instance, it does not deploy. Cause ~~~~~ -If the template was created by uploading an OVA file that was created +If the Template was created by uploading an OVA file that was created using vSphere Client, it is possible the OVA contained an ISO image. If -it does, the deployment of VMs from the template will fail. +it does, the deployment of Instances from the Template will fail. Solution ~~~~~~~~ -Remove the ISO and re-upload the template. +Remove the ISO and re-upload the Template. -Unable to power on virtual machine on VMware --------------------------------------------- +Unable to power on Instance on VMware +------------------------------------- Symptom ~~~~~~~ -Virtual machine does not power on. You might see errors like: +Instance does not power on. You might see errors like: - Unable to open Swap File - Unable to access a file since it is locked -- Unable to access Virtual machine configuration +- Unable to access Instance configuration Cause ~~~~~ A known issue on VMware machines. ESX hosts lock certain critical -virtual machine files and file systems to prevent concurrent changes. -Sometimes the files are not unlocked when the virtual machine is powered -off. When a virtual machine attempts to power on, it can not access -these critical files, and the virtual machine is unable to power on. +Instance files and file systems to prevent concurrent changes. +Sometimes the files are not unlocked when the Instance is powered +off. When an Instance attempts to power on, it can not access +these critical files, and the Instance is unable to power on. Solution @@ -241,7 +241,7 @@ load balancing rules so that they continue to function. Troubleshooting Internet Traffic -------------------------------- -Below are a few troubleshooting steps to check whats going wrong with your +Below are a few troubleshooting steps to check what's going wrong with your network... @@ -270,7 +270,7 @@ Trouble Shooting Steps If the pings dont work, run *tcpdump(8)* all over the place to check who is gobbling up the packets. Ultimately, if the switches are not - configured correctly, CloudStack networking wont work so fix the + configured correctly, CloudStack networking won't work so fix the physical networking issues before you proceed to the next steps #. Ensure `Traffic Labels `_ are set for the Zone. @@ -321,7 +321,7 @@ Trouble Shooting Steps #. KVM traffic labels require to be named as *"cloudbr0"*, *"cloudbr2"*, *"cloudbrN"* etc and the corresponding bridge must exist on the KVM hosts. If you create labels/bridges with any other names, CloudStack - (atleast earlier versions did) seems to ignore them. CloudStack does not + (at least earlier versions did) seems to ignore them. CloudStack does not create the physical bridges on the KVM hosts, you need to create them **before** before adding the host to Cloudstack. @@ -343,7 +343,7 @@ Trouble Shooting Steps interfaces bridge. This virtual interface to physical interface mapping is done automatically by CloudStack using the traffic label settings for the Zone. If you have provided correct settings and still dont have a - working working Internet, check the switching layer before you debug any + working Internet, check the switching layer before you debug any further. You can verify traffic using tcpdump on the virtual, physical and bridge interfaces. @@ -383,10 +383,10 @@ Trouble Shooting Steps #. The Internet would be accessible from both the SSVM and CPVM - instances by default. Their public IPs will also be directly pingable + Instances by default. Their public IPs will also be directly pingable from the Internet. Please note that these test would work only if your switches and traffic labels are configured correctly for your - environment. If your SSVM/CPVM cant reach the Internet, its very + environment. If your SSVM/CPVM can't reach the Internet, its very unlikely that the Virtual Router (VR) can also the reach the Internet suggesting that its either a switching issue or incorrectly assigned traffic labels. Fix the SSVM/CPVM issues before you debug VR issues. @@ -430,13 +430,13 @@ Trouble Shooting Steps round-trip min/avg/max/stddev = 28.098/44.021/69.179/17.998 ms #. However, the Virtual Router's (VR) Source NAT Public IP address - **WONT** be reachable until appropriate Ingress rules are + **WON'T** be reachable until appropriate Ingress rules are in place. You can add *Ingress* rules under *Network, Guest Network, IP Address, Firewall* setting page. .. image:: /_static/images/networking-ingress-rule.png -#. The VM Instances by default wont be able to access the Internet. Add +#. The Instances by default won't be able to access the Internet. Add Egress rules to permit traffic. .. image:: /_static/images/networking-egress-rule.png @@ -451,6 +451,6 @@ Trouble Shooting Steps In a vast majority of the cases, the problem has turned out to be at the switching layer where the L3 switches were configured incorrectly. -This section was contibuted by Shanker Balan and was originally published on +This section was contributed by Shanker Balan and was originally published on `Shapeblue's blog `_ diff --git a/source/adminguide/tuning.rst b/source/adminguide/tuning.rst index 75b09549f9..bb214602ee 100644 --- a/source/adminguide/tuning.rst +++ b/source/adminguide/tuning.rst @@ -36,22 +36,22 @@ Increase Management Server Maximum Memory If the Management Server is subject to high demand, the default maximum JVM memory allocation can be insufficient. To increase the memory: -#. Edit the Tomcat configuration file: +#. Edit the cloudstack-management.service configuration file at: .. code:: bash - /etc/cloudstack/management/tomcat6.conf + /etc/default/cloudstack-management -#. Change the command-line parameter -XmxNNNm to a higher value of N. +#. Change the command-line parameter from -XmxVVV to replace the VVV with an higher value. - For example, if the current value is -Xmx128m, change it to -Xmx1024m - or higher. + For example, if the current is the default value is -Xmx2G, change it to -Xmx12G + or another applicable value. Make sure not to go over about 2/3rd of the actual physical memory of the machine. #. To put the new setting into effect, restart the Management Server. .. code:: bash - # service cloudstack-management restart + # systemctl restart cloudstack-management For more information about memory issues, see "FAQ: Memory" at `Tomcat Wiki. `_ @@ -91,35 +91,151 @@ at `MySQL Reference Manual `_. -Set and Monitor Total VM Limits per Host ----------------------------------------- +Selecting Database Connection Pool Library +------------------------------------------ -The CloudStack administrator should monitor the total number of VM -instances in each cluster, and disable allocation to the cluster if the +CloudStack uses JDBC connection pool to manage and use database connections +in an optimal manner. It allows using either +`HikariCP `_ or +`DBCP 2 `_ based on the preference for +individual CloudStack databases - cloud, cloud_usage, simulator. + +The following settings can be configured in the db.properties configuration +file for the management server or usage server: +db.cloud.connectionPoolLib +db.cloud_usage.connectionPoolLib +db.simulator.connectionPoolLib + +To use DBCP 2, the value for the configuration must be set to 'dbcp'. An +empty value or 'hikaricp' will allow using HikariCP. + +For large-scale environments, HikariCP should perform better. For environments +running management server with constrained memory resources, using DBCP may +work better in terms of memory usage. + + +Monitor the Database Load +------------------------- + +The load of the database is monitored. By default the queries for each +minute are calculated in queries per second. Three values are retaint by +default. In the UI these are visible under the DB/Usage Server page +under the infrastructure menu. + +|dbLoadAverages.png| + +.. |dbLoadAverages.png| image:: /_static/images/dbLoadAverages.png + :alt: load averages as displayed in the UI + +The configuration variable 'database.server.stats.interval' can be set +to change the interval, which is 60 seconds by default. + +The value of 'database.server.stats.retention' can be changed to tweak +the number of values that are maintained. + + +Set and Monitor Total Instance Limits per Host +---------------------------------------------- + +The CloudStack administrator should monitor the total number of +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, +hosts failing, which would increase the Instance load on the other hosts as +the Instances are automatically redeployed. Consult the documentation for your +chosen hypervisor to find the maximum permitted number of Instances 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 +default limit. Monitor the Instance activity in each cluster at all times. +Keep the total number of Instances 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 +any given time, the total number of 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. +this number of Instances, use the CloudStack UI to disable allocation of more +Instances to the cluster. Configure XenServer dom0 Memory ------------------------------- Configure the XenServer dom0 settings to allocate more memory to dom0. -This can enable XenServer to handle larger numbers of virtual machines. +This can enable XenServer to handle larger numbers of Instances. We recommend 2940 MB of RAM for XenServer dom0. For instructions on how to do this, see `Citrix Knowledgebase Article `_.The article refers to XenServer 5.6, but the same information applies to XenServer 6 +Purging Expunged Resources +-------------------------- + +.. note:: + Currently only available for Instances and their linked resources. + +Over the time there are chances of piling up of millions of database records +for the removed or expunged resources. The presence of a lot of useless +records in the database can also affect the performance of the cloud so it is +needed to purge such entries in a systematic way. +CloudStack provides the following methods to allow purging of the expunged +resources and their database records: + +Using background task +~~~~~~~~~~~~~~~~~~~~~ + +A background task will run at regular intervals. The interval for the task and +other parameters for it such as resource types, start and end date and batch size +can also be controlled with the help of global settings. + +The following new global settings have been introduced which would allow +configuring background task for purging the expunged resources: + +.. cssclass:: table-striped table-bordered table-hover + +================================================ ================ =================================================================== +Global setting Default values Description +================================================ ================ =================================================================== +expunged.resources.purge.enabled false Whether to run a background task to purge the DB records of the expunged resources. +expunged.resources.purge.resources (empty) A comma-separated list of resource types that will be considered by the background task to purge the DB records of the expunged resources. Currently only VirtualMachine is supported. An empty value will result in considering all resource types for purging. +expunged.resources.purge.interval 86400 Interval (in seconds) for the background task to purge the DB records of the expunged resources. +expunged.resources.purge.delay 300 Initial delay (in seconds) to start the background task to purge the DB records of the expunged resources task. +expunged.resources.purge.batch.size 50 Batch size to be used during purging of the DB records of the expunged resources. +expunged.resources.purge.start.time (empty) Start time to be used by the background task to purge the DB records of the expunged resources. Use format yyyy-MM-dd or yyyy-MM-dd HH:mm:ss. +expunged.resources.purge.keep.past.days 30 The number of days in the past from the execution time of the background task to purge the DB records of the expunged resources for which the expunged resources must not be purged. To enable purging DB records of the expunged resource till the execution of the background task, set the value to zero. +================================================ ================ =================================================================== + + +Using API +~~~~~~~~~ + +An admin-only API `purgeExpungedResources` allows purging the expunged resources +with desired parameters. It will allow passing the following parameters - +resourcetype, batchsize, startdate, enddate. An example of purgeExpungedResources +API call is shown below: + + +.. parsed-literal:: + + > purge expungedresources startdate=2024-04-15 enddate=2024-04-20 resourcetype=VirtualMachine + { + "purgeexpungedresourcesresponse": { + "resourcecount": 6 + } + } + + +Using configuration in offerings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +..note:: + Available only for service offerings + +_purgeresources_ configuration for offerings can be used to allow immediately +purging a resource when it is expunged. The configuration can be set to true or +false _purgeresources_ parameter while creating the corresponding offerings. The +following global setting can be used to control the delay for purging the +resource after expunge: + +================================================ ================ =================================================================== +Global setting Default values Description +================================================ ================ =================================================================== +expunged.resource.purge.job.delay 180 Delay (in seconds) to execute the purging of the DB records of an expunged resource initiated by the configuration in the offering. Minimum value should be 180 seconds and if a lower value is set then the minimum value will be used. +================================================ ================ =================================================================== diff --git a/source/adminguide/ui.rst b/source/adminguide/ui.rst index b9fa334b0f..047d2f82cf 100644 --- a/source/adminguide/ui.rst +++ b/source/adminguide/ui.rst @@ -19,11 +19,11 @@ Log In to the UI ---------------- CloudStack provides a web-based UI that can be used by both -administrators and end users. The appropriate version of the UI is +administrators and end Users. The appropriate version of the UI is displayed depending on the credentials used to log in. The UI is available in all modern popular browsers including Chrome, Firefox, Edge and Safari. The UI uses API auto-discovery to discover APIs allowed for a logged-in -user and creates navigation and views based on that, and requires the following: +User and creates navigation and views based on that, and requires the following: - API discovery (listApis) enabled for all roles that must use the UI - Modern browsers that are `ES5-compliant `_ @@ -38,19 +38,23 @@ On a fresh Management Server installation, a guided tour splash screen appears. On later visits, you’ll see a login screen where you specify the following to proceed to your Dashboard: -Username -> The user ID of your account. The default username is admin. +Username -> The User ID of your Account. The default username is admin. -Password -> The password associated with the user ID. The password for +Password -> The password associated with the User ID. The password for the default username is password. -Domain -> If you are a root user, leave this field blank. +Domain -> If you are a root User, leave this field blank. -If you are a user in the sub-domains, enter the full path to the domain, +.. note:: + + Since 4.21 it is possible to login to a specific Project view by enabling the 'displayProjectFieldOnLogin' setting on config.json (which is disabled by default). Please refer to: :ref:`enable-login-to-project-view`. + +If you are a User in the sub-domains, enter the full path to the domain, excluding the root domain. For example, suppose multiple levels are created under the root domain, -such as Comp1/hr. The users in the Comp1 domain should enter Comp1 in -the Domain field, whereas the users in the Comp1/sales domain should +such as Comp1/hr. The Users in the Comp1 domain should enter Comp1 in +the Domain field, whereas the Users in the Comp1/sales domain should enter Comp1/sales. For more guidance about the choices that appear when you log in to this @@ -60,10 +64,10 @@ UI, see Logging In as the Root Administrator. End User's UI Overview ~~~~~~~~~~~~~~~~~~~~~~ -The CloudStack UI helps users of cloud infrastructure to view and use -their cloud resources, including virtual machines, templates and ISOs, -data volumes and snapshots, guest networks, and IP addresses. If the -user is a member or administrator of one or more CloudStack projects, +The CloudStack UI helps Users of cloud infrastructure to view and use +their cloud resources, including Instances, Templates and ISOs, +data volumes and Snapshots, Guest Networks, and IP addresses. If the +User is a member or administrator of one or more CloudStack projects, the UI can provide a project-oriented view. @@ -76,7 +80,7 @@ Root Administrator's UI Overview :align: left The CloudStack UI helps the CloudStack administrator provision, view, -and manage the cloud infrastructure, domains, user accounts, projects, +and manage the cloud infrastructure, domains, User Accounts, projects, and configuration settings. The first time you start the UI after a fresh Management Server installation, you can choose to follow a guided tour to provision your cloud infrastructure. On subsequent logins, the @@ -90,7 +94,7 @@ Logging In as the Root Administrator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After the Management Server software is installed and running, you can -run the CloudStack user interface. This UI is there to help you +run the CloudStack User interface. This UI is there to help you provision, view, and manage your cloud infrastructure. #. Open your favorite Web browser and go to this URL. Substitute the IP @@ -111,8 +115,8 @@ provision, view, and manage your cloud infrastructure. possible configuration so that you can get started right away. We'll help you set up a cloud with the following features: a single machine that runs CloudStack software and uses NFS to - provide storage; a single machine running VMs under the XenServer - or KVM hypervisor; and a shared public network. + provide storage; a single machine running Instances under the XenServer + or KVM hypervisor; and a shared public Network. The prompts in this guided tour should give you all the information you need, but if you want just a bit more detail, you @@ -123,8 +127,8 @@ provision, view, and manage your cloud infrastructure. deployment, or you are ready to start scaling up a trial cloud that you set up earlier with the basic setup screens. In the Administrator UI, you can start using the more powerful features - of CloudStack, such as advanced VLAN networking, high - availability, additional network elements such as load balancers + of CloudStack, such as advanced VLAN Networking, high + availability, additional Network elements such as load balancers and firewalls, and support for multiple hypervisors including Citrix XenServer, KVM, and VMware vSphere. @@ -135,10 +139,10 @@ provision, view, and manage your cloud infrastructure. chose experienced user, use the steps in :ref:`changing-root-password`. .. warning:: - You are logging in as the root administrator. This account manages the + You are logging in as the root administrator. This Account manages the CloudStack deployment, including physical infrastructure. The root administrator can modify configuration settings to change basic - functionality, create or delete user accounts, and take many actions + functionality, create or delete User Accounts, and take many actions that should be performed only by an authorized person. Please change the default password to a new, unique password. @@ -149,9 +153,9 @@ Changing the Root Password During installation and ongoing cloud administration, you will need to log in to the UI as the root administrator. The root administrator -account manages the CloudStack deployment, including physical +Account manages the CloudStack deployment, including physical infrastructure. The root administrator can modify configuration settings -to change basic functionality, create or delete user accounts, and take +to change basic functionality, create or delete User Accounts, and take many actions that should be performed only by an authorized person. When first installing CloudStack, be sure to change the default password to a new, unique value. @@ -163,12 +167,12 @@ new, unique value. http://:8080/client -#. Log in to the UI using the current root user ID and password. The +#. Log in to the UI using the current root User ID and password. The default is admin, password. #. Click Accounts. -#. Click the admin account name. +#. Click the admin Account name. #. Click View Users. @@ -178,26 +182,33 @@ new, unique value. #. Type the new password, and click OK. -Basic UI Customization +Basic UI Customisation ~~~~~~~~~~~~~~~~~~~~~~ Users can customize the CloudStack's user interface by means of a configuration file at /etc/cloudstack/management/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: -========== ================================================== -Property Description -========== ================================================== -apiBase Changes the suffix for the API endpoint -docBase Changes the base URL for the documentation -appTitle Changes the title of the portal -footer Changes the footer text -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. -========== ================================================== +======================================= ================================================================================================================================================================== +Property Description +======================================= ================================================================================================================================================================== +apiBase Changes the suffix for the API endpoint +docBase Changes the base URL for the documentation +appTitle Changes the title of the portal +footer Changes the footer text +loginFavicon Changes the favicon of the login page +loginFooter Configure to display text (HTML) in the footer at the login screen +loginTitle Changes the title of the login page +logo Changes the logo top-left side image +minilogo Changes the logo top-left side image when menu is collapsed +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 +imageSelectionInterface Allows specifying view for image(template/ISO) selection in several UI forms. Supported values are: "modern" and "legacy". Default view is "modern" +showUserCategoryForModernImageSelection Enables showing or hiding _User_ category in the *modern* image selection view which will show all user-owned images for the logged in user. Default value is true +showAllCategoryForModernImageSelection Enables showing or hiding _All_ category in the *modern* image selection view which will show all available images for the logged in user. Default value is false +======================================= ================================================================================================================================================================== .. parsed-literal:: @@ -205,6 +216,7 @@ error.500 Changes the image of error Internal Server Error. "docBase": "http://docs.cloudstack.apache.org/en/latest", "appTitle": "CloudStack", "footer": "Licensed under the Apache License, Version 2.0.", + "loginFooter": "By logging, you are accepting the usage policy", "logo": "assets/logo.svg", "banner": "assets/banner.svg", "error": { @@ -214,7 +226,7 @@ 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. Theme section provides following properties for customization: +Customisation 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. Theme section provides following properties for customisation: ============================= ================================================================ Property Description @@ -285,8 +297,46 @@ Some assorted primary theme colours: - Green: #52C41A - Purple: #722ED1 +The config.json also allows to configure a special-purpose card that shows on +the Account and project dashboards. This card is created using the `userCard` +section that has a configurable title, icon and a list of configurable links +that have a title, text (description), link and icon. + +.. parsed-literal:: + + "userCard": { + "title": "label.help", + "icon": "question-circle-outlined", + "links": [ + { + "title": "Documentation", + "text": "CloudStack documentation website", + "link": "https://docs.cloudstack.apache.org/en/latest/", + "icon": "read-outlined" + }, + { + "title": "API Documentation", + "text": "Refer to API documentation", + "link": "https://cloudstack.apache.org/api.html", + "icon": "api-outlined" + }, + { + "title": "Email Support", + "text": "Join CloudStack users mailing list to seek and provide support", + "link": "mailto:users-subscribe@cloudstack.apache.org", + "icon": "mail-outlined" + }, + { + "title": "Report Issue", + "text": "Submit a bug or improvement request", + "link": "https://github.com/apache/cloudstack/issues/new", + "icon": "bug-outlined" + } + ] + }, + Contextual help documentation URLs can be customized with the help of `docBase` and `docHelpMappings` properties. -To override a particular documentation URL, a mapping can be added for the URL path in the config. A documentation URL is formed by combining the `docBase` URL base and a path set in the source code. Adding a mapping for any particular path in the configuration will result in generating documetation URL with overridden path. +To override a particular documentation URL, a mapping can be added for the URL path in the config. A documentation URL is formed by combining the `docBase` URL base and a path set in the source code. Adding a mapping for any particular path in the configuration will result in generating documentation URL with overridden path. By default, `docHelpMappings` lists all existing documentation URL suffixes, mapped to themselves, in the configuration file that are used in the code. .. parsed-literal:: @@ -327,7 +377,7 @@ By default, `docHelpMappings` lists all existing documentation URL suffixes, map "adminguide/networking_and_traffic.html#creating-a-vpn-gateway-for-the-vpc": "adminguide/networking_and_traffic.html#creating-a-vpn-gateway-for-the-vpc", "adminguide/networking_and_traffic.html#enabling-or-disabling-static-nat": "adminguide/networking_and_traffic.html#enabling-or-disabling-static-nat", "adminguide/networking_and_traffic.html#load-balancing-across-tiers": "adminguide/networking_and_traffic.html#load-balancing-across-tiers", - "adminguide/networking_and_traffic.html#releasing-an-ip-address-alloted-to-a-vpc": "adminguide/networking_and_traffic.html#releasing-an-ip-address-alloted-to-a-vpc", + "adminguide/networking_and_traffic.html#releasing-an-ip-address-allotted-to-a-vpc": "adminguide/networking_and_traffic.html#releasing-an-ip-address-allotted-to-a-vpc", "adminguide/networking_and_traffic.html#reserving-public-ip-addresses-and-vlans-for-accounts": "adminguide/networking_and_traffic.html#reserving-public-ip-addresses-and-vlans-for-accounts", "adminguide/networking_and_traffic.html#restarting-and-removing-a-vpn-connection": "adminguide/networking_and_traffic.html#restarting-and-removing-a-vpn-connection", "adminguide/networking_and_traffic.html#security-groups": "adminguide/networking_and_traffic.html#security-groups", @@ -437,23 +487,104 @@ Example for adding custom plugins: plugins: [ { "name": "ExamplePlugin", - "icon": "appstore", + "icon": "appstore-outlined", "path": "example.html" }, { "name": "ExamplePlugin1", - "icon": "appstore", + "icon": "appstore-outlined", "path": "https://cloudstack.apache.org/" } ] ... } -`icon` for the plugin can be chosen from Ant Design icons listed at `Icon - Ant Design Vue https://www.antdv.com/components/icon/`_. +`icon` for the plugin can be chosen from Ant Design icons listed at `https://3x.antdv.com/components/icon `_. + +.. warning:: + Not all ant icons are supported at the moment. You will find a list of supported icons + within the github repository in ui/src/core/lazy_lib/icons_use.js. To use an icon you + need to transform the listed name. For example "PieChartOutlined" needs to be transformed + to "pie-chart-outlined", "ReadOutlined" needs to be transformed to "read-outlined". + For displaying a custom HTML in the plugin, HTML file can be stored in the CloudStack management server's web application directory on the server, i.e., */usr/share/cloudstack-management/webapp* and `path` can be set to the name of the file. For displaying a service or a web page, URL can be set as the `path` of the plugin. |ui-custom-plugin.png| + +Announcement Banner +=================== + +Admin can configure an **announcement banner** in `config.json` to display alerts or messages to all users. +This banner is useful for communicating important notices such as performance issues, scheduled maintenance, or general announcements. +To enable and customize the banner, use the `announcementBanner` section in the config.json file. + +This section supports the following properties: + +**Configuration Example** + +.. parsed-literal:: + + "announcementBanner": { + "enabled": true, + "showIcon": true, + "closable": true, + "persistDismissal": true, + "type": "warning", + "message": "Performance Notice: We're experiencing high load. Some operations may be slower than usual.", + "startDate": "2025-06-01T00:00:00Z", + "endDate": "2025-07-16T00:00:00Z" + } + +**Banner Display Example** + +Based on the configuration above, the following banner is shown in the user interface: + +.. image:: /_static/images/ui-announcement-banner.png + :align: center + :alt: UI Announcement banner + +-------- + +**Properties Description** + +- **enabled**: Enables or disables the announcement banner (`true` or `false`). +- **showIcon**: Displays an icon alongside the message. The icon corresponds to the banner `type`. +- **closable**: Allows users to close the banner. +- **persistDismissal**: Remembers the user's dismissal of the banner, so it doesn't reappear. +- **type**: Specifies the type of banner. Supported values are: + + - `info` + - `warning` + - `error` + - `success` + +- **message**: The HTML-formatted content displayed in the banner. +- **startDate** / **endDate**: Define the visibility window for the banner using ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). + +.. note:: + + - The `message` property supports basic HTML, allowing styled content such as `` tags for emphasis. + - Banner's background color changes based on `type` property value. White color is used for banner if `type` is not defined or has invalid value. + - Multi-line message is supported, however recommendation is to limit it to 2 lines. Content may overlap banner for more than 2 lines. + + +Instance Image Selection Customisation +------------------------------------- + +In the UI, there are several forms where the user needs to select an image (template/ISO) for an instance, such as deploying an instance, reinstalling an instance, creating a VNF appliance, etc. The image selection interface for these forms can be selected by the operator based on preference by specifying properties in the UI configuration file (config.json). + +The configuration property _imageSelectionInterface_ can be set to one of these values: modern or legacy. The default value is *modern*. + +When the *modern* interface is used, images will be categorized based on the guest operating system categories. Further customisation can be done using the configuration properties showUserCategoryForModernImageSelection and showAllCategoryForModernImageSelection to allow or disallow the display of additional categories. + +|ui-modern-image-selection.png| + +The *legacy* interface will display images based on templatefilter/isofilter, i.e., Featured, Community, My Templates/ISOs, and Shared. + +|ui-legacy-image-selection.png| + + Advanced UI Customisation ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -533,6 +664,23 @@ For the UI to work with different servers, it is necessary to configure the Ngin |ui-multiple-server-management.png| +.. _enable-login-to-project-view: + +Enable Login to Project View +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +User can use the file /etc/cloudstack/management/config.json to enable the Project field displayed on Login by the setting: + +============================= ================================================================= +Property Description +============================= ================================================================= +displayProjectFieldOnLogin Disabled by default. When enabled, login directly to Project view +============================= ================================================================= + +When the Project field is set and the Project exists, the user is directly directed to the Project view instead of the Default View. + +|ui-login-project-view.png| + Known Limitations ~~~~~~~~~~~~~~~~~ @@ -540,14 +688,23 @@ The following features are no longer supported or available in the UI but are st - Support for S3 based secondary storage. - NFS secondary staging storage list/resource view and add/update actions. -- SSL certificate for Guest network LB rule. +- SSL certificate for Guest Network LB rule. - Regions. .. |change-password.png| image:: /_static/images/change-password.png - :alt: button to change a user's password + :alt: button to change a User's password + +.. |ui-modern-image-selection.png| image:: /_static/images/ui-modern-image-selection.png + :alt: Modern Image Selection + +.. |ui-legacy-image-selection.png| image:: /_static/images/ui-legacy-image-selection.png + :alt: Legacy Image Selection .. |ui-custom-plugin.png| image:: /_static/images/ui-custom-plugin.png :alt: Custom plugin shown in UI with navigation .. |ui-multiple-server-management.png| image:: /_static/images/ui-multiple-server-management.png :alt: Custom plugin shown in UI with navigation + +.. |ui-login-project-view.png| image:: /_static/images/ui-login-project-view.png + :alt: Enabling the Project field on login diff --git a/source/adminguide/usage.rst b/source/adminguide/usage.rst index 654faea7d8..9363d7900f 100644 --- a/source/adminguide/usage.rst +++ b/source/adminguide/usage.rst @@ -28,8 +28,8 @@ will use CloudStack resource UUIDs instead of internal database IDs. To get description in the old format, an API parameter "oldformat" is introduced which is false by default. -The usage records show the amount of resources, such as VM run time or -template storage space, consumed by guest instances. +The usage records show the amount of resources, such as Instance run time or +Template storage space, consumed by Guest Instances. The Usage Server runs at least once per day. It can be configured to run multiple times per day. @@ -99,8 +99,8 @@ usage.sanity.check.interval The number of days between sanity checks. Set this in order to periodically search for records with erroneous data before issuing -customer invoices. For example, this checks for VM usage records created -after the VM was destroyed, and similar checks for templates, volumes, +customer invoices. For example, this checks for Instance usage records created +after the Instance was destroyed, and similar checks for Templates, Volumes, and so on. It also checks for usage times longer than the aggregation range. If any issue is found, the alert ALERT\_TYPE\_USAGE\_SANITY\_RESULT = 21 is sent. @@ -167,7 +167,7 @@ Setting Usage Limits -------------------- CloudStack provides several administrator control points for capping -resource usage by users. Some of these limits are global configuration +resource usage by Users. Some of these limits are global configuration parameters. Others are applied at the ROOT domain and may be overridden on a per-account basis. @@ -175,9 +175,9 @@ on a per-account basis. Globally Configured Limits ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In a zone, the guest virtual network has a 24 bit CIDR by default. This -limits the guest virtual network to 254 running instances. It can be -adjusted as needed, but this must be done before any instances are +In a zone, the guest virtual Network has a 24 bit CIDR by default. This +limits the guest virtual Network to 254 running Instances. It can be +adjusted as needed, but this must be done before any Instances are created in the zone. For example, 10.1.1.0/22 would provide for ~1000 addresses. @@ -188,29 +188,29 @@ The following table lists limits set in the Global Configuration: +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Parameter Name | Definition | +===========================+==================================================================================================================================================================================================================================================================================================+ -| max.account.public.ips | Number of public IP addresses that can be owned by an account | +| max.account.public.ips | Number of public IP addresses that can be owned by an Account | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| max.account.snapshots | Number of snapshots that can exist for an account | +| max.account.snapshots | Number of Templates that can exist for an Account | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| max.account.templates | Number of templates that can exist for an account | +| max.account.templates | Number of Templates that can exist for an Account | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| max.account.user.vms | Number of virtual machine instances that can exist for an account | +| max.account.user.vms | Number of Instances that can exist for an Account | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| max.account.volumes | Number of disk volumes that can exist for an account | +| max.account.volumes | Number of disk volumes that can exist for an Account | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| max.template.iso.size | Maximum size for a downloaded template or ISO in GB | +| max.template.iso.size | Maximum size for a downloaded Template or ISO in GB | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | max.volume.size.gb | Maximum size for a volume in GB | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| network.throttling.rate | Default data transfer rate in megabits per second allowed per user (supported on XenServer) | +| network.throttling.rate | Default data transfer rate in megabits per second allowed per User (supported on XenServer) | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshot.max.hourly | Maximum recurring hourly snapshots to be retained for a volume. If the limit is reached, early snapshots from the start of the hour are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring hourly snapshots can not be scheduled | +| snapshot.max.hourly | Maximum recurring hourly Templates to be retained for a volume. If the limit is reached, early Templates from the start of the hour are deleted so that newer ones can be saved. This limit does not apply to manual Templates. If set to 0, recurring hourly Templates can not be scheduled | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshot.max.daily | Maximum recurring daily snapshots to be retained for a volume. If the limit is reached, snapshots from the start of the day are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring daily snapshots can not be scheduled | +| snapshot.max.daily | Maximum recurring daily Templates to be retained for a volume. If the limit is reached, Templates from the start of the day are deleted so that newer ones can be saved. This limit does not apply to manual Templates. If set to 0, recurring daily Templates can not be scheduled | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshot.max.weekly | Maximum recurring weekly snapshots to be retained for a volume. If the limit is reached, snapshots from the beginning of the week are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring weekly snapshots can not be scheduled | +| snapshot.max.weekly | Maximum recurring weekly Templates to be retained for a volume. If the limit is reached, Templates from the beginning of the week are deleted so that newer ones can be saved. This limit does not apply to manual Templates. If set to 0, recurring weekly Templates can not be scheduled | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| snapshot.max.monthly | Maximum recurring monthly snapshots to be retained for a volume. If the limit is reached, snapshots from the beginning of the month are deleted so that newer ones can be saved. This limit does not apply to manual snapshots. If set to 0, recurring monthly snapshots can not be scheduled. | +| snapshot.max.monthly | Maximum recurring monthly Templates to be retained for a volume. If the limit is reached, Templates from the beginning of the month are deleted so that newer ones can be saved. This limit does not apply to manual Templates. If set to 0, recurring monthly Templates can not be scheduled. | +---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ To modify global configuration parameters, use the global configuration @@ -224,7 +224,7 @@ CloudStack allows you to control resource usage based on the types of resources, such as CPU, RAM, Primary storage, and Secondary storage. A new set of resource types has been added to the existing pool of resources to support the new customization model—need-basis usage, such -as large VM or small VM. The new resource types are now broadly +as large Instance or small Instance. The new resource types are now broadly classified as CPU, RAM, Primary storage, and Secondary storage. The root administrator is able to impose resource usage limit by the following resource types for Domain, Project, and Accounts. @@ -245,29 +245,55 @@ parameters have been added: =================================== ================================================================= Parameter Name Description =================================== ================================================================= -max.account.cpus Maximum number of CPU cores that can be used for an account. +max.account.cpus Maximum number of CPU cores that can be used for an Account. Default is 40. -max.account.ram (MB) Maximum RAM that can be used for an account. +max.account.ram (MB) Maximum RAM that can be used for an Account. Default is 40960. -max.account.primary.storage (GB) Maximum primary storage space that can be used for an account. +max.account.gpus Maximum number of GPUs that can be used for an Account. + Default is 20. +max.account.primary.storage (GB) Maximum primary storage space that can be used for an Account. Default is 200. -max.account.secondary.storage (GB) Maximum secondary storage space that can be used for an account. +max.account.secondary.storage (GB) Maximum secondary storage space that can be used for an Account. Default is 400. -max.project.cpus Maximum number of CPU cores that can be used for an account. +max.project.cpus Maximum number of CPU cores that can be used for a Project. Default is 40. -max.project.ram (MB) Maximum RAM that can be used for an account. +max.project.ram (MB) Maximum RAM that can be used for a Project. Default is 40960. -max.project.primary.storage (GB) Maximum primary storage space that can be used for an account. +max.project.gpus Maximum number of GPUs that can be used for a Project. + Default is 20. +max.project.primary.storage (GB) Maximum primary storage space that can be used for a Project. Default is 200. -max.project.secondary.storage (GB) Maximum secondary storage space that can be used for an account. +max.project.secondary.storage (GB) Maximum secondary storage space that can be used for a Project. Default is 400. =================================== ================================================================= +The GPU devices are not detached when the Instance is stopped. Therefore, +the GPU devices for stopped Instances are counted towards the resource limits. +To avoid this, the administrator can set the `gpu.detach.on.stop` global +setting to `true` to detach the GPU devices when the Instance is stopped. + +The administrator can also set limits for specific tagged host and storage +resources for an account or domain. Such tags must be specified in the following +global settings: + +- `resource.limit.host.tags` - A comma-separated list of tags for host resource limits. It applies to resource types - User VM, CPU, Memory. +- `resource.limit.storage.tags` - A comma-separated list of tags for storage resource limits. It applies to resource types - Volume, Primary storage. + +The limits for tagged resources are a subset of the overall limits and the maximum +can be the value of the overall limit for the particular resource type. + +|accountlimits.png| + +The administrator can view used and available capacity of such tagged resource +along with the overall capacities in the zone and cluster view in the UI. + +|zonecapacities.png| + User Permission ~~~~~~~~~~~~~~~ -The root administrator, domain administrators and users are able to list +The root administrator, domain administrators and Users are able to list resources. Ensure that proper logs are maintained in the ``vmops.log`` and ``api.log`` files. @@ -275,10 +301,10 @@ and ``api.log`` files. limits. - The domain administrators are allowed to list and change these - resource limits only for the sub-domains and accounts under their own + resource limits only for the sub-domains and Accounts under their own domain or the sub-domains. -- The end users will the privilege to list resource limits. Use the +- The end Users will the privilege to list resource limits. Use the listResourceLimits API. @@ -289,47 +315,47 @@ Limit Usage Considerations volume and not the physical size— the actual consumed size on disk in case of thin provisioning. -- If the admin reduces the resource limit for an account and set it to +- If the admin reduces the resource limit for an Account and set it to less than the resources that are currently being consumed, the - existing VMs/templates/volumes are not destroyed. Limits are imposed - only if the user under that account tries to execute a new operation + existing Instances/Templates/Volumes are not destroyed. Limits are imposed + only if the User under that Account tries to execute a new operation using any of these resources. For example, the existing behavior in - the case of a VM are: + the case of an Instance are: - - migrateVirtualMachine: The users under that account will be able - to migrate the running VM into any other host without facing any + - migrateVirtualMachine: The Users under that Account will be able + to migrate the running Instance into any other host without facing any limit issue. - - recoverVirtualMachine: Destroyed VMs cannot be recovered. + - recoverVirtualMachine: Destroyed Instances cannot be recovered. - For any resource type, if a domain has limit X, sub-domains or accounts under that domain can have there own limits. However, the - sum of resource allocated to a sub-domain or accounts under the + sum of resource allocated to a sub-domain or Accounts under the domain at any point of time should not exceed the value X. For example, if a domain has the CPU limit of 40 and the sub-domain - D1 and account A1 can have limits of 30 each, but at any point of + D1 and Account A1 can have limits of 30 each, but at any point of time the resource allocated to D1 and A1 should not exceed the limit of 40. - If any operation needs to pass through two of more resource limit check, then the lower of 2 limits will be enforced, For example: if - an account has the VM limit of 10 and CPU limit of 20, and a user - under that account requests 5 VMs of 4 CPUs each. The user can deploy - 5 more VMs because VM limit is 10. However, the user cannot deploy - any more instances because the CPU limit has been exhausted. + an Account has the Instance limit of 10 and CPU limit of 20, and a User + under that Account requests 5 Instances of 4 CPUs each. The User can deploy + 5 more Instances because Instance limit is 10. However, the User cannot deploy + any more Instances because the CPU limit has been exhausted. Limiting Resource Usage in a Domain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CloudStack allows the configuration of limits on a domain basis. With a -domain limit in place, all users still have their account limits. They +domain limit in place, all Users still have their Account limits. They are additionally limited, as a group, to not exceed the resource limits -set on their domain. Domain limits aggregate the usage of all accounts -in the domain as well as all the accounts in all the sub-domains of that +set on their domain. Domain limits aggregate the usage of all Accounts +in the domain as well as all the Accounts in all the sub-domains of that domain. Limits set at the root domain level apply to the sum of resource -usage by the accounts in all the domains and sub-domains below that root +usage by the Accounts in all the domains and sub-domains below that root domain. To set a domain limit: @@ -353,7 +379,7 @@ To set a domain limit: - Instance Limits - The number of instances that can be used in a domain. + The number of Instances that can be used in a domain. - Public IP Limits @@ -365,11 +391,11 @@ To set a domain limit: - Snapshot Limits - The number of snapshots that can be created in a domain. + The number of Templates that can be created in a domain. - Template Limits - The number of templates that can be registered in a domain. + The number of Templates that can be registered in a domain. - VPC limits @@ -397,19 +423,19 @@ To set a domain limit: Default Account Resource Limits ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can limit resource use by accounts. The default limits are set by -using Global configuration parameters, and they affect all accounts +You can limit resource use by Accounts. The default limits are set by +using Global configuration parameters, and they affect all Accounts within a cloud. The relevant parameters are those beginning with max.account, for example: max.account.snapshots. -To override a default limit for a particular account, set a per-account +To override a default limit for a particular Account, set a per-account resource limit. #. Log in to the CloudStack UI. #. In the left navigation tree, click Accounts. -#. Select the account you want to modify. The current limits are +#. Select the Account you want to modify. The current limits are displayed. A value of -1 shows that there is no limit in place. @@ -424,61 +450,61 @@ resource limit. - Instance Limits - The number of instances that can be used in an account. + The number of Instances that can be used in an Account. The default is 20. - Public IP Limits - The number of public IP addresses that can be used in an account. + The number of public IP addresses that can be used in an Account. The default is 20. - Volume Limits - The number of disk volumes that can be created in an account. + The number of disk volumes that can be created in an Account. The default is 20. - Snapshot Limits - The number of snapshots that can be created in an account. + The number of Templates that can be created in an Account. The default is 20. - Template Limits - The number of templates that can be registered in an account. + The number of Templates that can be registered in an Account. The default is 20. - VPC limits - The number of VPCs that can be created in an account. + The number of VPCs that can be created in an Account. The default is 20. - CPU limits - The number of CPU cores that can be used for an account. + The number of CPU cores that can be used for an Account. The default is 40. - Memory limits (MB) - The number of RAM that can be used for an account. + The number of RAM that can be used for an Account. The default is 40960. - Primary Storage limits (GB) - The primary storage space that can be used for an account. + The primary storage space that can be used for an Account. The default is 200. - Secondary Storage limits (GB) - The secondary storage space that can be used for an account. + The secondary storage space that can be used for an Account. The default is 400. @@ -488,40 +514,40 @@ resource limit. Usage Record Format ------------------- -Virtual Machine Usage Record Format -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Instance Usage Record Format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For running and allocated virtual machine usage, the following fields +For running and allocated Instance usage, the following fields exist in a usage record: -- account – name of the account +- account – name of the Account -- accountid – ID of the account +- accountid – ID of the Account -- domainid – ID of the domain in which this account resides +- domainid – ID of the domain in which this Account resides - zoneid – Zone where the usage occurred - description – A string describing what the usage record is tracking - usage – String representation of the usage, including the units of - usage (e.g. 'Hrs' for VM running time) + usage (e.g. 'Hrs' for Instance running time) - usagetype – A number representing the usage type (see Usage Types) - rawusage – A number representing the actual usage in hours -- virtualMachineId – The ID of the virtual machine +- virtualMachineId – The ID of the Instance -- name – The name of the virtual machine +- name – The name of the Instance - offeringid – The ID of the service offering -- templateid – The ID of the template or the ID of the parent template. - The parent template value is present when the current template was +- templateid – The ID of the Template or the ID of the parent Template. + The parent Template value is present when the current Template was created from a volume. -- usageid – Virtual machine +- usageid – Instance - type – Hypervisor @@ -532,14 +558,14 @@ exist in a usage record: Network Usage Record Format ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For network usage (bytes sent/received), the following fields exist in a +For Network usage (bytes sent/received), the following fields exist in a usage record. -- account – name of the account +- account – name of the Account -- accountid – ID of the account +- accountid – ID of the Account -- domainid – ID of the domain in which this account resides +- domainid – ID of the domain in which this Account resides - zoneid – Zone where the usage occurred @@ -562,9 +588,9 @@ IP Address Usage Record Format For IP address usage the following fields exist in a usage record. -- account - name of the account +- account - name of the Account -- accountid - ID of the account +- accountid - ID of the Account - domainid - ID of the domain in which this account resides @@ -617,7 +643,7 @@ For disk volumes, the following fields exist in a usage record. - type – Hypervisor -- templateid – ROOT template ID +- templateid – ROOT Template ID - size – The amount of storage allocated @@ -645,14 +671,14 @@ Template, ISO, and Snapshot Usage Record Format - rawusage – A number representing the actual usage in hours -- usageid – The ID of the the template, ISO, or snapshot +- usageid – The ID of the Template, ISO, or Template - offeringid – The ID of the disk offering -- templateid – – Included only for templates (usage type 7). Source - template ID. +- templateid – – Included only for Templates (usage type 7). Source + Template ID. -- size – Size of the template, ISO, or snapshot +- size – Size of the Template, ISO, or Template - startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record @@ -680,8 +706,6 @@ Load Balancer Policy or Port Forwarding Rule Usage Record Format - usageid - ID of the load balancer policy or port forwarding rule -- usagetype - A number representing the usage type (see Usage Types) - - startdate, enddate - The range of time for which the usage is aggregated; see Dates in the Usage Record @@ -706,15 +730,11 @@ Network Offering Usage Record Format - rawusage – A number representing the actual usage in hours -- usageid – ID of the network offering - -- usagetype – A number representing the usage type (see Usage Types) - -- offeringid – Network offering ID +- offeringid – ID of the Network offering -- virtualMachineId – The ID of the virtual machine +- virtualmachineid – The ID of the Instance -- virtualMachineId – The ID of the virtual machine +- isdefault – The default nic of the Instance - startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record @@ -740,9 +760,7 @@ VPN User Usage Record Format - rawusage – A number representing the actual usage in hours -- usageid – VPN user ID - -- usagetype – A number representing the usage type (see Usage Types) +- usageid – VPN User ID - startdate, enddate – The range of time for which the usage is aggregated; see Dates in the Usage Record @@ -755,108 +773,108 @@ The following table shows all usage types. .. cssclass:: table-striped table-bordered table-hover -+------------------+-----------------------------------+-----------------------+ -| Type ID | Type Name | Description | -+==================+===================================+=======================+ -| 1 | RUNNING\_VM | Tracks the total | -| | | running time of a VM | -| | | per usage record | -| | | period. If the VM is | -| | | upgraded during the | -| | | usage period, you | -| | | will get a separate | -| | | Usage Record for the | -| | | new upgraded VM. | -+------------------+-----------------------------------+-----------------------+ -| 2 | ALLOCATED\_VM | Tracks the total time | -| | | the VM has been | -| | | created to the time | -| | | when it has been | -| | | destroyed. This usage | -| | | type is also useful | -| | | in determining usage | -| | | for specific | -| | | templates such as | -| | | Windows-based | -| | | templates. | -+------------------+-----------------------------------+-----------------------+ -| 3 | IP\_ADDRESS | Tracks the public IP | -| | | address owned by the | -| | | account. | -+------------------+-----------------------------------+-----------------------+ -| 4 | NETWORK\_BYTES\_SENT | Tracks the total | -| | | number of bytes sent | -| | | by all the VMs for an | -| | | account. Cloud.com | -| | | does not currently | -| | | track network traffic | -| | | per VM. | -+------------------+-----------------------------------+-----------------------+ -| 5 | NETWORK\_BYTES\_RECEIVED | Tracks the total | -| | | number of bytes | -| | | received by all the | -| | | VMs for an account. | -| | | Cloud.com does not | -| | | currently track | -| | | network traffic per | -| | | VM. | -+------------------+-----------------------------------+-----------------------+ -| 6 | VOLUME | Tracks the total time | -| | | a disk volume has | -| | | been created to the | -| | | time when it has been | -| | | destroyed. | -+------------------+-----------------------------------+-----------------------+ -| 7 | TEMPLATE | Tracks the total time | -| | | a template (either | -| | | created from a | -| | | snapshot or uploaded | -| | | to the cloud) has | -| | | been created to the | -| | | time it has been | -| | | destroyed. The size | -| | | of the template is | -| | | also returned. | -+------------------+-----------------------------------+-----------------------+ -| 8 | ISO | Tracks the total time | -| | | an ISO has been | -| | | uploaded to the time | -| | | it has been removed | -| | | from the cloud. The | -| | | size of the ISO is | -| | | also returned. | -+------------------+-----------------------------------+-----------------------+ -| 9 | SNAPSHOT | Tracks the total time | -| | | from when a snapshot | -| | | has been created to | -| | | the time it have been | -| | | destroyed. | -+------------------+-----------------------------------+-----------------------+ -| 11 | LOAD\_BALANCER\_POLICY | Tracks the total time | -| | | a load balancer | -| | | policy has been | -| | | created to the time | -| | | it has been removed. | -| | | Cloud.com does not | -| | | track whether a VM | -| | | has been assigned to | -| | | a policy. | -+------------------+-----------------------------------+-----------------------+ -| 12 | PORT\_FORWARDING\_RULE | Tracks the time from | -| | | when a port | -| | | forwarding rule was | -| | | created until the | -| | | time it was removed. | -+------------------+-----------------------------------+-----------------------+ -| 13 | NETWORK\_OFFERING | The time from when a | -| | | network offering was | -| | | assigned to a VM | -| | | until it is removed. | -+------------------+-----------------------------------+-----------------------+ -| 14 | VPN\_USERS | The time from when a | -| | | VPN user is created | -| | | until it is removed. | -+------------------+-----------------------------------+-----------------------+ ++------------------+-----------------------------------+-----------------------------+ +| Type ID | Type Name | Description | ++==================+===================================+=============================+ +| 1 | RUNNING\_VM | Tracks the total | +| | | running time of an Instance | +| | | per usage record | +| | | period. If the Instance is | +| | | upgraded during the | +| | | usage period, you | +| | | will get a separate | +| | | Usage Record for the | +| | | new upgraded Instance. | ++------------------+-----------------------------------+-----------------------------+ +| 2 | ALLOCATED\_VM | Tracks the total time | +| | | the Instance has been | +| | | created to the time | +| | | when it has been | +| | | destroyed. This usage | +| | | type is also useful | +| | | in determining usage | +| | | for specific | +| | | Templates such as | +| | | Windows-based | +| | | Templates. | ++------------------+-----------------------------------+-----------------------------+ +| 3 | IP\_ADDRESS | Tracks the public IP | +| | | address owned by the | +| | | account. | ++------------------+-----------------------------------+-----------------------------+ +| 4 | NETWORK\_BYTES\_SENT | Tracks the total | +| | | number of bytes sent | +| | | by all the Instances for an | +| | | account. Cloud.com | +| | | does not currently | +| | | track Network traffic | +| | | per Instance. | ++------------------+-----------------------------------+-----------------------------+ +| 5 | NETWORK\_BYTES\_RECEIVED | Tracks the total | +| | | number of bytes | +| | | received by all the | +| | | Instances for an account. | +| | | Cloud.com does not | +| | | currently track | +| | | Network traffic per | +| | | Instance. | ++------------------+-----------------------------------+-----------------------------+ +| 6 | VOLUME | Tracks the total time | +| | | a disk volume has | +| | | been created to the | +| | | time when it has been | +| | | destroyed. | ++------------------+-----------------------------------+-----------------------------+ +| 7 | TEMPLATE | Tracks the total time | +| | | a Template (either | +| | | created from a | +| | | Template or uploaded | +| | | to the cloud) has | +| | | been created to the | +| | | time it has been | +| | | destroyed. The size | +| | | of the Template is | +| | | also returned. | ++------------------+-----------------------------------+-----------------------------+ +| 8 | ISO | Tracks the total time | +| | | an ISO has been | +| | | uploaded to the time | +| | | it has been removed | +| | | from the cloud. The | +| | | size of the ISO is | +| | | also returned. | ++------------------+-----------------------------------+-----------------------------+ +| 9 | SNAPSHOT | Tracks the total time | +| | | from when a Template | +| | | has been created to | +| | | the time it have been | +| | | destroyed. | ++------------------+-----------------------------------+-----------------------------+ +| 11 | LOAD\_BALANCER\_POLICY | Tracks the total time | +| | | a load balancer | +| | | policy has been | +| | | created to the time | +| | | it has been removed. | +| | | Cloud.com does not | +| | | track whether an Instance | +| | | has been assigned to | +| | | a policy. | ++------------------+-----------------------------------+-----------------------------+ +| 12 | PORT\_FORWARDING\_RULE | Tracks the time from | +| | | when a port | +| | | forwarding rule was | +| | | created until the | +| | | time it was removed. | ++------------------+-----------------------------------+-----------------------------+ +| 13 | NETWORK\_OFFERING | The time from when a | +| | | Network offering was | +| | | assigned to an Instance | +| | | until it is removed. | ++------------------+-----------------------------------+-----------------------------+ +| 14 | VPN\_USERS | The time from when a | +| | | VPN User is created | +| | | until it is removed. | ++------------------+-----------------------------------+-----------------------------+ Example response from listUsageRecords @@ -900,34 +918,38 @@ Usage records include a start date and an end date. These dates define the period of time for which the raw usage number was calculated. If daily aggregation is used, the start date is midnight on the day in question and the end date is 23:59:59 on the day in question (with one -exception; see below). A virtual machine could have been deployed at +exception; see below). An Instance could have been deployed at noon on that day, stopped at 6pm on that day, then started up again at 11pm. When usage is calculated on that day, there will be 7 hours of -running VM usage (usage type 1) and 12 hours of allocated VM usage -(usage type 2). If the same virtual machine runs for the entire next -day, there will 24 hours of both running VM usage (type 1) and allocated -VM usage (type 2). +running Instance usage (usage type 1) and 12 hours of allocated Instance usage +(usage type 2). If the same Instance runs for the entire next +day, there will 24 hours of both running Instance usage (type 1) and allocated +Instance usage (type 2). -Note: The start date is not the time a virtual machine was started, and -the end date is not the time when a virtual machine was stopped. The +Note: The start date is not the time an Instance was started, and +the end date is not the time when an Instance was stopped. The start and end dates give the time range within which usage was calculated. -For network usage, the start date and end date again define the range in -which the number of bytes transferred was calculated. If a user +For Network usage, the start date and end date again define the range in +which the number of bytes transferred was calculated. If a User downloads 10 MB and uploads 1 MB in one day, there will be two records, one showing the 10 megabytes received and one showing the 1 megabyte sent. There is one case where the start date and end date do not correspond to midnight and 11:59:59pm when daily aggregation is used. This occurs only -for network usage records. When the usage server has more than one day's +for Network usage records. When the usage server has more than one day's worth of unprocessed data, the old data will be included in the aggregation period. The start date in the usage record will show the date and time of the earliest event. For other types of usage, such as -IP addresses and VMs, the old unprocessed data is not included in daily +IP addresses and Instances, the old unprocessed data is not included in daily aggregation. .. |editbutton.png| image:: /_static/images/edit-icon.png :alt: edits the settings. +.. |accountlimits.png| image:: /_static/images/account-limits.png + :alt: Configure account resource limits in UI. +.. |zonecapacities.png| image:: /_static/images/zone-capacities.png + :alt: Resource capacities for a zone. diff --git a/source/adminguide/veeam_plugin.rst b/source/adminguide/veeam_plugin.rst index 14424fb5d1..eaa63632ef 100644 --- a/source/adminguide/veeam_plugin.rst +++ b/source/adminguide/veeam_plugin.rst @@ -13,30 +13,30 @@ specific language governing permissions and limitations under the License. -.. _Veeam Backup and Recovery Plugin: +.. _Veeam Backup and Replication Plugin: -Veeam Backup and Recovery Plugin +Veeam Backup and Replication Plugin ================================= -About the Veeam Backup and Recovery Plugin +About the Veeam Backup and Replication 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. +#. 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 + 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). +#. 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 extremely 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 + is not assigned to any Instance 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 Instances #. Veeam's API is not complete and therefore a mix of API commands and powershell commands (via SSH) are employed. @@ -44,21 +44,21 @@ There are a couple of important concepts to understand before working with the V remaining image(s) -Installing Veeam Backup and Recovery for use with CloudStack +Installing Veeam Backup and Replication for use with CloudStack ------------------------------------------------------------- -The B&R Veeam plugin has been tested against Veeam Backup and Recovery 9.5 update 4b (Enterprise version). The +The B&R Veeam plugin has been tested against Veeam Backup and Replication 11 and 12. 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 +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 Backup and Replication 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. @@ -77,7 +77,7 @@ but at a high level you need to have done the following; 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 +#. As noted above, a dummy VM tag is required in order to create Template jobs which don't contain any Instances. 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| @@ -86,25 +86,25 @@ Creating Template jobs |BnR-CreateDummyTag.jpg| -#. Now create the template job in Veeam Backup and Replication Manager. using the New Backup Job (Virtual Machine) wizard. +#. Now create the Template job in Veeam Backup and Replication Manager. Using the New Backup Job (Instance) 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 + #. In the Instances 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 + of other advanced 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 + #. 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, + 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| @@ -115,7 +115,7 @@ Creating Template jobs 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. +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: @@ -126,15 +126,19 @@ Plug-in specific settings: .. cssclass:: table-striped table-bordered table-hover -==================================== ======================== -Configuration Description -==================================== ======================== -backup.plugin.veeam.url Veeam B&R server URL. Default: http://: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 -==================================== ======================== +======================================= ======================== +Configuration Description +======================================= ======================== +backup.framework.provider.plugin The backup and recovery provider plugin. Set this to 'veeam'. +backup.plugin.veeam.url Veeam B&R server URL. Default: http://:9398/api/ +backup.plugin.veeam.version Veeam B&R server version. CloudStack will get Veeam server version via PowerShell commands if it is 0 or not set +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 +backup.plugin.veeam.task.poll.interval The time interval in seconds when the management server polls for Veeam task status. Default: 5 +backup.plugin.veeam.task.poll.max.retry The max number of retrying times when the management server polls for Veeam task status. Default: 120 +======================================= ======================== .. |BnR-DummyTagCategory.jpg| image:: /_static/images/BnR-DummyTagCategory.jpg diff --git a/source/adminguide/virtual_machines.rst b/source/adminguide/virtual_machines.rst index 6737591d3d..3a07f40a89 100644 --- a/source/adminguide/virtual_machines.rst +++ b/source/adminguide/virtual_machines.rst @@ -13,87 +13,87 @@ specific language governing permissions and limitations under the License. -About Working with Virtual Machines -=================================== +About Working with Instances +============================ CloudStack provides administrators with complete control over the -lifecycle of all guest VMs executing in the cloud. CloudStack provides -several guest management operations for end users and administrators. -VMs may be stopped, started, rebooted, and destroyed. +lifecycle of all guest Instances executing in the cloud. CloudStack provides +several guest management operations for end Users and administrators. +Instances may be stopped, started, rebooted, and destroyed. -Guest VMs have a name and group. VM names and groups are opaque to -CloudStack and are available for end users to organize their VMs. Each -VM can have three names for use in different contexts. Only two of these -names can be controlled by the user: +Guest Instances have a name and group. Instance names and groups are opaque to +CloudStack and are available for end Users to organize their Instances. Each +Instance can have three names for use in different contexts. Only two of these +names can be controlled by the User: - Instance name – a unique, immutable ID that is generated by - CloudStack and can not be modified by the user. This name conforms to + CloudStack and can not be modified by the User. This name conforms to the requirements in IETF RFC 1123. - Display name – the name displayed in the CloudStack web UI. Can be - set by the user. Defaults to instance name. + set by the User. Defaults to Instance name. -- Name – host name that the DHCP server assigns to the VM. Can be set - by the user. Defaults to instance name +- Name – host name that the DHCP server assigns to the Instance. Can be set + by the User. Defaults to Instance name .. note:: - You can append the display name of a guest VM to its internal name. - For more information, see `“Appending a Name to the Guest VM’s + You can append the display name of a guest Instance to its internal name. + For more information, see `“Appending a Name to the Guest Instance’s Internal Name” <#appending-a-name-to-the-guest-vms-internal-name>`_. -Guest VMs can be configured to be Highly Available (HA). An HA-enabled -VM is monitored by the system. If the system detects that the VM is -down, it will attempt to restart the VM, possibly on a different host. -For more information, see HA-Enabled Virtual Machines on +Guest Instances can be configured to be Highly Available (HA). An HA-enabled +Instance is monitored by the system. If the system detects that the Instance is +down, it will attempt to restart the Instance, possibly on a different host. +For more information, see HA-Enabled Instances on -Each new VM is allocated one public IP address. When the VM is started, +Each new Instance is allocated one public IP address. When the Instance is started, CloudStack automatically creates a static NAT between this public IP -address and the private IP address of the VM. +address and the private IP address of the Instance. If elastic IP is in use (with the NetScaler load balancer), the IP -address initially allocated to the new VM is not marked as elastic. The -user must replace the automatically configured IP with a specifically +address initially allocated to the new Instance is not marked as elastic. The +User must replace the automatically configured IP with a specifically acquired elastic IP, and set up the static NAT mapping between this new -IP and the guest VM’s private IP. The VM’s original IP address is then +IP and the guest Instance’s private IP. The Instance’s original IP address is then released and returned to the pool of available public IPs. Optionally, -you can also decide not to allocate a public IP to a VM in an +you can also decide not to allocate a public IP to an Instance in an EIP-enabled Basic zone. For more information on Elastic IP, see `“About Elastic IP” `_. -CloudStack cannot distinguish a guest VM that was shut down by the user -(such as with the “shutdown” command in Linux) from a VM that shut down -unexpectedly. If an HA-enabled VM is shut down from inside the VM, -CloudStack will restart it. To shut down an HA-enabled VM, you must go +CloudStack cannot distinguish a guest Instance that was shut down by the User +(such as with the “shutdown” command in Linux) from an Instance that shut down +unexpectedly. If an HA-enabled Instance is shut down from inside the Instance, +CloudStack will restart it. To shut down an HA-enabled Instance, you must go through the CloudStack UI or API. .. note:: - **Monitor VMs for Max Capacity** + **Monitor Instances 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 + The CloudStack administrator should monitor the total number of 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, + hosts failing, which would increase the Instance load on the other hosts as + the Instances are automatically redeployed. Consult the documentation for your + chosen hypervisor to find the maximum permitted number of Instances 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 + default limit. Monitor the Instance activity in each cluster at all times. + Keep the total number of Instances 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 + any given time, the total number of 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. + this number of Instances, use the CloudStack UI to disable allocation of more + Instances to the cluster. -VM Lifecycle -============ +Instance Lifecycle +================== -Virtual machines can be in the following states: +Instances can be in the following states: - Created - Running @@ -109,132 +109,172 @@ With the intermediate states of - Expunging -Creating VMs ------------- +Creating Instances +------------------ -Virtual machines are usually created from a template. Users can also -create blank virtual machines. A blank virtual machine is a virtual -machine without an OS template. Users can attach an ISO file and install +Instance are usually created from a Template. Users can also +create blank Instances. A blank Instance is a virtual +machine without an OS Template. Users can attach an ISO file and install the OS from the CD/DVD-ROM. .. note:: - You can create a VM without starting it. You can determine whether the - VM needs to be started as part of the VM deployment. A request parameter, + You can create an Instance without starting it. You can determine whether the + Instance needs to be started as part of the Instance deployment. A request parameter, startVM, in the deployVm API provides this feature. For more information, see the Developer's Guide. -To create a VM from a template: +To create an Instance from a Template: -#. Log in to the CloudStack UI as an administrator or user. +#. Log in to the CloudStack UI as an administrator or User. #. In the left navigation bar, click Compute -> Instances. #. Click the Add Instance button. -#. Select a zone. Admin users will have the option to select a pod, cluster or host. +#. Select a zone. Admin Users will have the option to select a pod, cluster or host. -#. Select a template or ISO. For more information about how the templates came +#. Select a Template or ISO. For more information about how the Templates came to be in this list, see `*Working with Templates* `_. -#. Be sure that the hardware you have allows starting the selected - service offering. +#. Select a service offering. Be sure that the hardware you have allows starting the selected + service offering. If the selected template has a tag associated with it + then only supported service offerings will be available for the selection. #. Select a disk offering. -#. Select/Add a network. +#. Select/Add a Network. .. note:: - VMware only: If the selected template contains OVF properties, different deployment options or configurations, + VMware only: If the selected Template contains OVF properties, different deployment options or configurations, multiple NICs or end-user license agreements, then the wizard will display these properties. See `“Support for Virtual Appliances” `_. -#. Click Launch Virtual Machine and your VM will be created and started. +#. Click Launch Instance and your Instance will be created and started. .. note:: - For security reason, the internal name of the VM is visible + For security reason, the internal name of the Instance is visible only to the root admin. .. note:: **XenServer** - Windows VMs running on XenServer require PV drivers, - which may be provided in the template or added after the VM is + Windows Instances running on XenServer require PV drivers, + which may be provided in the Template or added after the Instance is created. The PV drivers are necessary for essential management functions such as mounting additional volumes and ISO images, live migration, and graceful shutdown. + **VMware** + + If the rootDiskController and dataDiskController are not specified for an Instance using Instance details and + these are set to use osdefault in the Template or the global configuration, then CloudStack tries to find the + recommended disk controllers for it using guest OS from the hypervisor. In some specific cases, it may create + issues with the Instance deployment or start operation. To overcome this, a specific disk controller can be + specified at the Instance or Template level. For an existing Instance its settings can be updated while it is in + stopped state by admin. + Install Required Tools and Drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Be sure the following are installed on each VM: +Be sure the following are installed on each Instance: -- For XenServer, install PV drivers and Xen tools on each VM. This will +- For XenServer, install PV drivers and Xen tools on each Instance. 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 +- For vSphere, install VMware Tools on each Instance. 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; +- Create each Instance 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 +- 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 +- If a User deploys an Instance 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 + Instance, then the User can inform CloudStack using the updateVirtualMachine API. After installing the tools and updating the - virtual machine, stop and start the VM. + Instance, stop and start the Instance. + +Instance Metdata +~~~~~~~~~~~~~~~~ +CloudStack provides different means for controlling an instance's metadata. -Accessing VMs -------------- +- 'extraconfig' parameter of 'deployVirtualMachine' or 'updateVirtualMachine' API methods + can be used for setting different metadata parameters for an instance. +- Zone-level configurations - 'vm.metadata.manufacturer' and 'vm.metadata.product' can be used + to set the manufacturer and product respectively in the instance metadata. However, a + custom value for these parameters may affect cloud-init functionality for the instance + when used with CloudStack datasource. One of the requirement for cloud-init functionality + to work with CloudStack datasource is that product value should contain 'CloudStack'. -Any user can access their own virtual machines. The administrator can -access all VMs running in the cloud. -To access a VM through the CloudStack UI: +Accessing Instances +------------------- -#. Log in to the CloudStack UI as a user or admin. +Any User can access their own Instances. The administrator can +access all Instances running in the cloud. -#. Click Compute -> Instances, then click the name of a running VM. +To access an Instance through the CloudStack UI: + +#. Log in to the CloudStack UI as a User or admin. + +#. Click Compute -> Instances, then click the name of a running Instance. #. Click the View Console button |console-icon.png|. -To access a VM directly over the network: +To access an Instance directly over the Network: -#. The VM must have some port open to incoming traffic. For example, in - a basic zone, a new VM might be assigned to a security group which +#. The Instance must have some port open to incoming traffic. For example, in + a basic zone, a new Instance might be assigned to a security group which allows incoming traffic. This depends on what security group you - picked when creating the VM. In other cases, you can open a port by + picked when creating the Instance. In other cases, you can open a port by setting up a port forwarding policy. See `“IP Forwarding and Firewalling” `_. -#. If a port is open but you can not access the VM using ssh, it’s - possible that ssh is not already enabled on the VM. This will depend - on whether ssh is enabled in the template you picked when creating - the VM. Access the VM through the CloudStack UI and enable ssh on the - machine using the commands for the VM’s operating system. +#. If a port is open but you can not access the Instance using ssh, it’s + possible that ssh is not already enabled on the Instance. This will depend + on whether ssh is enabled in the Template you picked when creating + the Instance. Access the Instance through the CloudStack UI and enable ssh on the + machine using the commands for the Instance’s operating system. -#. If the network has an external firewall device, you will need to +#. If the Network has an external firewall device, you will need to create a firewall rule to allow access. See `“IP Forwarding and Firewalling” `_. -Stopping and Starting VMs -------------------------- +Securing Instance Console Access (KVM only) +------------------------------------------- + +CloudStack provides a way to secure VNC console access on KVM using the CA Framework certificates to enable TLS on VNC on each KVM host. + +To enable TLS on a KVM host, navigate to the host and click on: Provision Host Security Keys (or invoke the provisionCertificate API for the host): -Once a VM instance is created, you can stop, restart, or delete it as -needed. In the CloudStack UI, click Instances, select the VM, and use +- When a new host is added and it is provisioned with a certificate, TLS will also be enabled for VNC +- The running Instances on a secured host will continue to be VNC unencrypted unless they are stopped and started. +- New Instances created on a secured host will be VNC encrypted. + +Once the administrator concludes the certificates provisioning on Cloudstack, the console access for new Instances on the hosts will be encrypted. CloudStack displays the console of the Instances through the noVNC viewer embedded in the console proxy System VMs. +The CloudStack Users will notice the encrypted VNC sessions display a green bar stating the session is encrypted as in the image below. Also, the tab title includes ‘(TLS backend)’ when the session is encrypted. + +.. note:: + CloudStack will give access to the certificates to the group defined on the /etc/libvirt/qemu.conf file (or the last one defined on the file in case of multiple lines setting a group). + +Stopping and Starting Instance +------------------------------- + +Once an Instance is created, you can stop, restart, or delete it as +needed. In the CloudStack UI, click Instances, select the Instance, and use the Stop, Start, Reboot, and Destroy buttons. A stop will attempt to gracefully shut down the operating system, via @@ -244,82 +284,142 @@ 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 +a start command reconfigures the Instance 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. +When starting an Instance, admin Users have the option to specify a pod, cluster, or host. + +.. note:: + When starting an instance, it's possible to specify a host for deployment, + even if the host's tags don't match the instance's tags. This can lead to a + mismatch between the VM's tags and the host's tags, which may not be + desirable. + + To avoid this, refer to the :ref:`strict-host-tags` section -Deleting VMs -------------------------- +Deleting Instance +------------------ -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. +Users can delete their own Instance. A running Instance will be abruptly stopped +before it is deleted. Administrators can delete any Instance. -To delete a virtual machine: +To delete an Instance: -#. Log in to the CloudStack UI as a user or admin. +#. Log in to the CloudStack UI as a User or admin. #. In the left navigation, click Compute -> Instances. -#. Choose the VM that you want to delete. +#. Choose the Instance that you want to delete. #. Click the Destroy Instance button. |Destroyinstance.png| #. 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, +When an Instance 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. +consumes logical resources. Global settings control the maximum time from an Instance +being destroyed, to the physical disks being removed. When the Instance and its rooot disk +have been deleted, the Instance is said to have been expunged. -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. +Once an Instance is **expunged**, it cannot be recovered. All the +resources used by the Instance will be reclaimed by the system, +This includes the Instance’s IP address. -Managing Virtual Machines -========================= +Managing Instances +================== -Changing the VM Name, OS, or Group +Scheduling operations on an Instance ------------------------------------- -After a VM is created, you can modify the display name, operating +After an Instance is created, you can schedule Instance lifecycle operations using cron expressions. The operations that can be scheduled are: + +- Start +- Stop +- Reboot +- Force Stop +- Force Reboot + +To schedule an operation on an Instance through the UI: + +#. Log in to the CloudStack UI as a User or admin. + +#. In the left navigation, click Instances. + +#. Click the Instance that you want to schedule the operation on. + +#. On the Instance details page, click the **Schedule** button. |vm-schedule-tab.png| + +#. Click on **Add schedule** button to add a new schedule or click on Edit button |EditButton.png| to edit + an existing schedule. |vm-schedule-form.png| + +#. Configure the schedule as per requirements: + + - **Description**: Enter a description for the schedule. If left empty, it's generated on the basis of action and the schedule. + + - **Action**: Select the action to be triggered by the schedule. Can't be changed once the schedule has been created. + + - **Schedule**: Select the frequency using cron format at which the action should be triggered. + For example, `* * * * *` will trigger the job every minute. + + - **Timezone**: Select the timezone in which the schedule should be triggered. + + - **Start Date**: Date at the specified time zone after which the schedule becomes active. + Defaults to current timestamp plus 1 minute. + + - **End Date**: Date at the specified time zone before which the schedule is active. + If not set, schedule won't become inactive. + + .. note:: + It's not possible to remove the end date once it's configured. + + + +#. Click OK to save the schedule. + + .. note:: + If multiple schedules are configured for an Instance and the scheduled time coincides, then only the schedule which was created first + will be executed and the rest will be skipped. + + +Changing the Instance Name, OS, or Group +---------------------------------------- + +After an Instance is created, you can modify the display name, operating system, and the group it belongs to. -To access a VM through the CloudStack UI: +To access an Instance through the CloudStack UI: -#. Log in to the CloudStack UI as a user or admin. +#. Log in to the CloudStack UI as a User or admin. #. In the left navigation, click Instances. -#. Select the VM that you want to modify. +#. Select the Instance that you want to modify. -#. Click the Stop button to stop the VM. |StopButton.png| +#. Click the Stop button to stop the Instance. |StopButton.png| #. Click Edit. |EditButton.png| #. Make the desired changes to the following: #. **Display name**: Enter a new display name if you want to change the - name of the VM. + name of the Instance. #. **OS Type**: Select the desired operating system. -#. **Group**: Enter the group name for the VM. +#. **Group**: Enter the group name for the Instance. #. Click Apply. -Appending a Name to the Guest VM’s Internal Name --------------------------------------------------- +Appending a Name to the Guest Instance’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 guest VM with a name. You can set this name as the internal name so that the vCenter can use it to identify the guest VM. A new global parameter, vm.instancename.flag, has now been added to achieve this functionality. +Every guest Instance has an internal name. The host uses the internal name to identify the guest Instances. CloudStack gives you an option to provide a guest Instance with a name. You can set this name as the internal name so that the vCenter can use it to identify the guest Instance. A new global parameter, vm.instancename.flag, has now been added to achieve this functionality. -The default format of the internal name is i---, where i.n is the value of the global configuration - instance.name. However, If vm.instancename.flag is set to true, and if a name is provided during the creation of a guest VM, the name is appended to the internal name of the guest VM on the host. This makes the internal name format as i---. The default value of vm.instancename.flag is set to false. This feature is intended to make the correlation between instance names and internal names easier in large data center deployments. +The default format of the internal name is i---, where i.n is the value of the global configuration - instance.name. However, If vm.instancename.flag is set to true, and if a name is provided during the creation of a guest Instance, the name is appended to the internal name of the guest Instance on the host. This makes the internal name format as i---. The default value of vm.instancename.flag is set to false. This feature is intended to make the correlation between Instance names and internal names easier in large data center deployments. -The following table explains how a VM name is displayed in different scenarios. +The following table explains how an Instance name is displayed in different scenarios. .. cssclass:: table-striped table-bordered table-hover @@ -337,48 +437,94 @@ The following table explains how a VM name is displayed in different scenarios. represents the value of the global configuration - instance.name -Changing the Service Offering for a VM ----------------------------------------- +Instance delete protection +-------------------------- + +CloudStack protects instances from accidental deletion using a delete protection +flag, which is false by default. When delete protection is enabled for an +instance, it cannot be deleted through the UI or API. It can only be deleted +after removing delete protection from the instance. + +Delete protection can be enabled for an instance via updateVirtualMachine API. + +.. code:: bash -To upgrade or downgrade the level of compute resources available to a -virtual machine, you can change the VM's compute offering. + cmk update virtualmachine id= deleteprotection=true -#. Log in to the CloudStack UI as a user or admin. +To remove delete protection, use the following command: + +.. code:: bash + + cmk update virtualmachine id= deleteprotection=false + +To enable/disable delete protection for an instance using the UI, follow these steps: + +#. Log in to the CloudStack UI as a User or admin. + +#. In the navigation menu on the left, click Instances under Compute. + +#. Choose the Instance for which you want to enable/disable delete protection. + +#. Click on the Edit button |EditButton.png| + +#. Toggle the Delete Protection switch to enable or disable delete protection. + +#. Click Ok button to save the changes. + +.. note:: + The instance delete protection is only considered when the instance is being + deleted through the UI or via `destroyVirtualMachine` or `expungeVirtualMachine` + API. If the domain/project is deleted, the instances under the domain/project + will be deleted irrespective of the delete protection status. + + +Changing the Service Offering for an Instance +--------------------------------------------- + +To upgrade or downgrade the level of compute resources available to an +Instance, you can change the Instance's compute offering. + +#. Log in to the CloudStack UI as a User or admin. #. In the left navigation, click Instances. -#. Choose the VM that you want to work with. +#. Choose the Instance that you want to work with. -#. (Skip this step if you have enabled dynamic VM scaling; see +#. (Skip this step if you have enabled dynamic Instance scaling; see :ref:`cpu-and-memory-scaling`.) - Click the Stop button to stop the VM. |StopButton.png| + Click the Stop button to stop the Instance. |StopButton.png| #. Click the Change Service button. |ChangeServiceButton.png| The Change service dialog box is displayed. -#. Select the offering you want to apply to the selected VM. +#. Select the offering you want to apply to the selected Instance. #. Click OK. +.. note:: + When changing the service offering for an instance, it's possible to have a + mismatch of host tags which can be problematic. + + For more information on how to prevent this, see :ref:`strict-host-tags`. .. _cpu-and-memory-scaling: -CPU and Memory Scaling for Running VMs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +CPU and Memory Scaling for Running Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Supported on VMware and XenServer) It is not always possible to accurately predict the CPU and RAM -requirements when you first deploy a VM. You might need to increase -these resources at any time during the life of a VM. You can dynamically -modify CPU and RAM levels to scale up these resources for a running VM +requirements when you first deploy an Instance. You might need to increase +these resources at any time during the life of an Instance. You can dynamically +modify CPU and RAM levels to scale up these resources for a running Instance without incurring any downtime. Dynamic CPU and RAM scaling can be used in the following cases: -- User VMs on hosts running VMware and XenServer. +- User Instances on hosts running VMware and XenServer. - System VMs on VMware. @@ -386,21 +532,21 @@ Dynamic CPU and RAM scaling can be used in the following cases: machine. - The new requested CPU and RAM values must be within the constraints - allowed by the hypervisor and the VM operating system. + allowed by the hypervisor and the Instance operating system. -- New VMs that are created after the installation of CloudStack 4.2 can +- New Instances that are created after the installation of CloudStack 4.2 can use the dynamic scaling feature. If you are upgrading from a previous - version of CloudStack, your existing VMs created with previous + version of CloudStack, your existing Instances created with previous versions will not have the dynamic scaling capability unless you update them using the following procedure. -Updating Existing VMs -~~~~~~~~~~~~~~~~~~~~~ +Enable Dynamic Scaling for Existing Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are upgrading from a previous version of CloudStack, and you want -your existing VMs created with previous versions to have the dynamic -scaling capability, update the VMs using the following steps: +your existing Instances created with previous versions to have the dynamic +scaling capability, update the Instances using the following steps: #. Make sure the zone-level setting enable.dynamic.scale.vm is set to true. In the left navigation bar of the CloudStack UI, click @@ -408,9 +554,9 @@ scaling capability, update the VMs using the following steps: the Settings tab. #. Install Xen tools (for XenServer hosts) or VMware Tools (for VMware - hosts) on each VM if they are not already installed. + hosts) on each Instance if they are not already installed. -#. Stop the VM. +#. Stop the Instance. #. Click the Edit button. @@ -418,7 +564,7 @@ scaling capability, update the VMs using the following steps: #. Click Apply. -#. Restart the VM. +#. Restart the Instance. Configuring Dynamic CPU and RAM Scaling @@ -434,48 +580,48 @@ variables: = 2. Along with these global configurations, the following options need to be enabled -to make a VM dynamically scalable +to make an Instance dynamically scalable -- Template from which VM is created needs to have Xen tools (for XenServer hosts) +- Template from which Instance is created needs to have Xen tools (for XenServer hosts) or VMware Tools (for VMware hosts) and it should have 'Dynamically Scalable' flag set to true. -- Service Offering of the VM should have 'Dynamic Scaling Enabled' flag set to true. +- Service Offering of the Instance should have 'Dynamic Scaling Enabled' flag set to true. By default, this flag is true when a Service Offering is created. -- While deploying a VM, User or Admin needs to mark 'Dynamic Scaling Enabled' to true. +- While deploying an Instance, User or Admin needs to mark 'Dynamic Scaling Enabled' to true. By default this flag is set to true. -If any of the above settings are false then VM cannot be configured as dynamically scalable. +If any of the above settings are false then the Instance cannot be configured as dynamically scalable. How to Dynamically Scale CPU and RAM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To modify the CPU and/or RAM capacity of a virtual machine, you need to -change the compute offering of the VM to a new compute offering that has +To modify the CPU and/or RAM capacity of an Instance, you need to +change the compute offering of the Instance to a new compute offering that has the desired CPU value and RAM value and 'Dynamic Scaling Enabled' flag as true. -You can use the same steps described above in `“Changing the Service Offering for a -VM” <#changing-the-service-offering-for-a-vm>`_, but skip the step where you -stop the virtual machine. Of course, you might have to create a new +You can use the same steps described above in `“Changing the Service Offering for an +Instance” <#changing-the-service-offering-for-a-vm>`_, but skip the step where you +stop the Instance. Of course, you might have to create a new compute offering first. When you submit a dynamic scaling request, the resources will be scaled up on the current host if possible. If the host does not have enough -resources, the VM will be live migrated to another host in the same +resources, the Instance will be live migrated to another host in the same cluster. If there is no host in the cluster that can fulfill the -requested level of CPU and RAM, the scaling operation will fail. The VM +requested level of CPU and RAM, the scaling operation will fail. The Instance will continue to run as it was before. Limitations ~~~~~~~~~~~ -- You can not do dynamic scaling for system VMs on XenServer. +- You can not do dynamic scaling for system Instances on XenServer. - CloudStack will not check to be sure that the new CPU and RAM levels - are compatible with the OS running on the VM. + are compatible with the OS running on the Instance. -- When scaling memory or CPU for a Linux VM on VMware, you might need +- When scaling memory or CPU for a Linux Instance on VMware, you might need to run scripts in addition to the other steps mentioned above. For more information, see `Hot adding memory in Linux (1012764) `_ @@ -487,94 +633,135 @@ Limitations information, see `https://issues.apache.org/jira/browse/CLOUDSTACK-1809 `_. -- On VMs running Linux 64-bit and Windows 7 32-bit operating systems, - if the VM is initially assigned a RAM of less than 3 GB, it can be +- On Instances running Linux 64-bit and Windows 7 32-bit operating systems, + if the Instance is initially assigned a RAM of less than 3 GB, it can be dynamically scaled up to 3 GB, but not more. This is due to a known issue with these operating systems, which will freeze if an attempt is made to dynamically scale from less than 3 GB to more than 3 GB. +- On KVM, not all versions of Qemu/KVM may support dynamic scaling. Some combinations may result CPU or memory related failures during Instance deployment. + -Resetting the Virtual Machine Root Volume on Reboot ---------------------------------------------------- +Resetting the Instance Root Volume on Reboot +-------------------------------------------- -For secure environments, and to ensure that VM state is not persisted +For secure environments, and to ensure that Instance state is not persisted across reboots, you can reset the root disk. For more information, see -`“Reset VM to New Root Disk on +`“Reset Instance to New Root Disk on Reboot” `_. -Moving VMs Between Hosts (Manual Live Migration) ------------------------------------------------- +Moving Instances Between Hosts (Manual Live Migration) +------------------------------------------------------ -The CloudStack administrator can move a running VM from one host to -another without interrupting service to users or going into maintenance +The CloudStack administrator can move a running Instance from one host to +another without interrupting service to Users or going into maintenance mode. This is called manual live migration, and can be done under the following conditions: -- The root administrator is logged in. Domain admins and users can not - perform manual live migration of VMs. +- The root administrator is logged in. Domain admins and Users can not + perform manual live migration of Instances. -- The VM is running. Stopped VMs can not be live migrated. +- The Instance is running. Stopped Instances can not be live migrated. - The destination host must have enough available capacity. If not, the - VM will remain in the "migrating" state until memory becomes + Instance will remain in the "migrating" state until memory becomes available. -- (KVM) The VM must not be using local disk storage. (On XenServer and - VMware, VM live migration with local disk is enabled by CloudStack +- (KVM) The Instance must not be using local disk storage. (On XenServer and + VMware, Instance live migration with local disk is enabled by CloudStack support for XenMotion and vMotion.) - (KVM) The destination host must be in the same cluster as the - original host. (On XenServer and VMware, VM live migration from one + original host. (On XenServer and VMware, Instance live migration from one cluster to another is enabled by CloudStack support for XenMotion and vMotion.) -To manually live migrate a virtual machine +To manually live migrate an Instance -#. Log in to the CloudStack UI as a user or admin. +#. Log in to the CloudStack UI as root administrator. #. In the left navigation, click Instances. -#. Choose the VM that you want to migrate. +#. Choose the Instance that you want to migrate. #. Click the Migrate Instance button. |Migrateinstance.png| #. From the list of suitable hosts, choose the one to which you want to - move the VM. + move the Instance. .. note:: - If the VM's storage has to be migrated along with the VM, this will + If the Instance's storage has to be migrated along with the Instance, this will be noted in the host list. CloudStack will take care of the storage migration for you. #. Click OK. .. note:: - (KVM) If the VM's storage has to be migrated along with the VM, from a mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 'migrateVirtualMachineWithVolume' API has to be used. There is no UI integration for this feature. + (KVM) If the Instance's storage has to be migrated along with the Instance, from a mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 'migrateVirtualMachineWithVolume' API has to be used. There is no UI integration for this feature. (CloudMonkey) > migrate virtualmachinewithvolume virtualmachineid= hostid= migrateto[i].volume= migrateto[i].pool= - where i in [0,..,N] and N = number of volumes of the virtual machine + where i in [0,..,N] and N = number of volumes of the Instance + +.. note:: + During live migration, there can be a mismatch between the instance's tags + with the destination host's tags which might be undesirable. + + For more details on how to prevent this, see :ref:`strict-host-tags`. + +Moving Instance's Volumes Between Storage Pools (offline volume Migration) +-------------------------------------------------------------------------- + +The CloudStack administrator can move a stopped Instance's volumes from one +storage pool to another within the cluster. This is called offline volume +migration, and can be done under the following conditions: + +- The root administrator is logged in. Domain admins and Users can not + perform offline volume migration of Instances. + +- The Instance is stopped. + +- The destination storage pool must have enough available capacity. + +- UI operation allows only migrating the root volume upon selecting the + storage pool. To migrate all volumes to the desired storage pools + the 'migrateVirtualMachineWithVolume' API has to be used by providing + 'migrateto' map parameter. + + +To perform stopped Instance's volumes migration + +#. Log in to the CloudStack UI as root administrator. + +#. In the left navigation, click Instances. + +#. Choose the Instance that you want to migrate. + +#. Click the Migrate Instance button. |Migrateinstance.png| +#. From the list of suitable storage pools, choose the one to which you want to + move the Instance root volume. +#. Click OK. -Assigning VMs to Hosts ----------------------- +Assigning Instances 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? +At any point in time, each Instance is running on a single +host. How does CloudStack determine which host to place an Instance on? There are several ways: - Automatic default host allocation. CloudStack can automatically pick - the most appropriate host to run each virtual machine. + the most appropriate host to run each Instance. - 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 + 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. + 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 @@ -582,24 +769,24 @@ There are several ways: 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 +- Admin Users preferences. Administrators have the option to specify a + pod, cluster, or host to run the Instance 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 +- End User preferences. Users can not control exactly which host will + run a given Instance, but they can specify a zone for the Instance. + CloudStack is then restricted to allocating the Instance 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 + be used to specify which host an Instance 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. + 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) whether - VMs should run on separate hosts or on the same host. This feature is to - let users specify whether certain VMs will or will not be on the same host. +- Affinity groups. By defining affinity groups and assigning Instances to + them, the User or administrator can influence (but not dictate) whether + Instances should run on separate hosts or on the same host. This feature is to + let Users specify whether certain Instances will or will not be on the same host. - CloudStack also provides a pluggable interface for adding new allocators. These custom allocators can provide any policy the @@ -609,19 +796,31 @@ There are several ways: 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 -either the same or separate hosts. This feature is to let users specify -the affinity groups to which a VM can belong. 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 +By defining affinity groups and assigning Instances to them, the User or +administrator can influence (but not dictate) which Instances should run on +either the same or separate hosts. This feature allows Users to specify +the affinity groups to which an Instance can belong. Instances with the +same “host anti-affinity” type won’t be on the same host, which serves to +increase fault tolerance. If a host fails, another Instance offering the same +service (for example, hosting the User's website) is still up and running on another host. -It also lets the user specify that VMs with the same "host affinity" type -run on the same host. This can be useful in ensuring connectivity and minimum -latency in between guest VMs. +It also allows Users to specify that Instances with the same "host affinity" type +must run on the same host, which can be useful in ensuring connectivity and low +latency between guest Instances. +"non-strict host anti-affinity" is similar to, but more flexible than, "host +anti-affinity". In that case Instances are deployed to different hosts as long as +there are enough hosts to satisfy the requirement, otherwise they might be +deployed to the same host. +"non-strict host affinity" is similar to, but more flexible than, "host affinity", +Instances are ideally placed together in the same host, but only if possible. -The scope of an affinity group is per user account. +.. note:: When using VMware and enabling DRS, the results are + unpredictable. VMware implements similar functionality but + CloudStack does not leverage the VMware feature. As VMware is + unaware of the CloudStack definition of affinity groups, its DRS + may go against the desired configuration. + +The scope of an affinity group is on an Account level. Creating a New Affinity Group @@ -629,7 +828,7 @@ Creating a New Affinity Group To add an affinity group: -#. Log in to the CloudStack UI as an administrator or user. +#. Log in to the CloudStack UI as an administrator or User. #. In the left navigation bar, click Affinity Groups. @@ -641,36 +840,41 @@ To add an affinity group: - Description. Any desired text to tell more about the purpose of the group. - - Type. CloudStack supports two types of affinity groups. "Host - Anti-Affinity" and "Host Affinity". "Host Anti-Affinity" indicates - that the VMs in this group should avoid being placed on the same - host with each other. "Host Affinity" on the other hand indicates - that VMs in this group should be placed on the same host. + - Type. CloudStack supports four types of affinity groups. "host + anti-affinity", "host affinity", "non-strict host affinity" and + "non-strict host anti-affinity". "host anti-affinity" indicates + that the Instances in this group must not be placed on the same + host with each other. "host affinity" on the other hand indicates + that Instances in this group must be placed on the same host. + "non-strict host anti-affinity" indicates that Instances in this group + should be deployed to different hosts. + "non-strict host affinity" indicates that Instances in this group + should not be deployed to same hosts. -Assign a New VM to an Affinity Group -'''''''''''''''''''''''''''''''''''' +Assign a New Instance to an Affinity Group +'''''''''''''''''''''''''''''''''''''''''' -To assign a new VM to an affinity group: +To assign a new Instance to an affinity group: -- Create the VM as usual, as described in `“Creating - VMs” `_. In the Add Instance +- Create the Instance as usual, as described in `“Creating + Instances” `_. 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 -'''''''''''''''''''''''''''''''''''''''' +Change Affinity Group for an Existing Instance +'''''''''''''''''''''''''''''''''''''''''''''' -To assign an existing VM to an affinity group: +To assign an existing Instance to an affinity group: -#. Log in to the CloudStack UI as an administrator or user. +#. 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. +#. Click the name of the Instance you want to work with. -#. Stop the VM by clicking the Stop button. +#. Stop the Instance by clicking the Stop button. #. Click the Change Affinity button. |change-affinity-button.png| @@ -678,7 +882,7 @@ To assign an existing VM to an affinity group: View Members of an Affinity Group ''''''''''''''''''''''''''''''''' -To see which VMs are currently assigned to a particular affinity group: +To see which Instances are currently assigned to a particular affinity group: #. In the left navigation bar, click Affinity Groups. @@ -686,7 +890,7 @@ To see which VMs are currently assigned to a particular affinity group: #. 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 + From here, you can click the name of any Instance in the list to access all its details and controls. @@ -701,56 +905,238 @@ To delete an affinity group: #. Click Delete. - Any VM that is a member of the affinity group will be disassociated + Any Instance 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 + normally on the current hosts, but if the Instance is restarted, it will no longer follow the host allocation rules from its former affinity group. -Changing a VM's Base Image --------------------------- +Determine Destination Host of Instances with Non-Strict Affinity Groups +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +(Non-Strict Host Anti-Affinity and Non-Strict Host Affinity only) + +The destination host of Instances with Non-Strict Affinity Groups are determined +by the host priorities. The hosts have default priority as 0. If there is a +Instance in the same Non-Strict Host Anti-Affinity group on the host, the host +priority will be decreased by 1. If there is an Instance in the same Non-Strict Host +Affinity group on the host, the host priority will be increased by 1. All +available hosts are reordered by host priorities when deploy or start an Instance. + +Here are some examples how host priorities are calculated. + +- Example 1: Instance has a non-strict host anti-affinity group. + +If Host-1 has 2 Instances in the group, Host-2 has 3 Instances in the group. +Host-1 priority is -2, Host-2 priority is -3. If there are only 2 hosts, +Instance will be deployed to Host-1 as it has higher priority (-2 > -3). + +- Example 2: Instance has a non-strict host affinity group. + +If Host-1 has 2 Instances in the group, Host-2 has 3 Instances in the group. +Host-1 priority is 2, Host-2 priority is 3. If there are only 2 hosts, +Instance will be deployed to Host-2 (3 >2). + +- Example 3: Instance has a non-strict host affinity group and also a non-strict host anti-affinity group. + +If Host-1 has 2 Instances in the non-strict host affinity group, and +3 Instances in the non-strict host anti-affinity group. Host-1 priority is +calculated by: + + 0 (default) + 2 (Instances in non-strict host affinity group) - 3 (Instances in the non-strict host anti-affinity group) = -1 -Every VM is created from a base image, which is a template or ISO which + +Changing an Instance's Base Image +--------------------------------- + +Every Instance is created from a base image, which is a Template or ISO which has been created and stored in CloudStack. Both cloud administrators and -end users can create and modify templates, ISOs, and VMs. +end Users can create and modify Templates, ISOs, and Instances. -In CloudStack, you can change an existing VM's base image from one -template to another, or from one ISO to another. (You can not change -from an ISO to a template, or from a template to an ISO). +In CloudStack, you can change an existing Instance's base image from one +Template to another, or from one ISO to another. (You can not change +from an ISO to a Template, or from a Template to an ISO). -For example, suppose there is a template based on a particular operating +For example, suppose there is a Template based on a particular operating system, and the OS vendor releases a software patch. The administrator -or user naturally wants to apply the patch and then make sure existing -VMs start using it. Whether a software update is involved or not, it's -also possible to simply switch a VM from its current template to any -other desired template. - -To change a VM's base image, call the restoreVirtualMachine API command -and pass in the virtual machine ID and a new template ID. The template -ID parameter may refer to either a template or an ISO, depending on -which type of base image the VM was already using (it must match the -previous type of image). When this call occurs, the VM's root disk is +or User naturally wants to apply the patch and then make sure existing +Instances start using it. Whether a software update is involved or not, it's +also possible to simply switch an Instance from its current Template to any +other desired Template. + +To change an Instance's base image, call the restoreVirtualMachine API command +and pass in the Instance ID and a new Template ID. The Template +ID parameter may refer to either a Template or an ISO, depending on +which type of base image the Instance was already using (it must match the +previous type of image). When this call occurs, the Instance's root disk is first destroyed, then a new root disk is created from the source -designated in the template ID parameter. The new root disk is attached -to the VM, and now the VM is based on the new template. +designated in the Template ID parameter. The new root disk is attached +to the Instance, and now the Instance is based on the new Template. -You can also omit the template ID parameter from the -restoreVirtualMachine call. In this case, the VM's root disk is -destroyed and recreated, but from the same template or ISO that was -already in use by the VM. +You can also omit the Template ID parameter from the +restoreVirtualMachine call. In this case, the Instance's root disk is +destroyed and recreated, but from the same Template or ISO that was +already in use by the Instance. +Instance Lease +-------------- -Advanced VM Instance Settings ------------------------------ +CloudStack offers the option to create Instances with a Lease. A Lease defines a set time period after which a selected action, +such as stopping or destroying the instance, will be automatically performed. This helps optimize cloud resource usage by automatically +freeing up resources that are no longer in use. + +If a user needs an instance only for a limited time, this option can be very helpful. +When deploying an instance, users can either choose a Compute Offering that includes Instance Lease support or enable it specifically for that instance, +setting the number of days after which the instance should be stopped or destroyed once their task is complete. + + +**Configuring Instance Lease feature** + +The cloud administrator can use global configuration variables to control the behavior of Instance Lease. +To set these variables, API or CloudStack UI can be used: + +======================================= ======================== +Configuration Description +======================================= ======================== +instance.lease.enabled Indicates whether to enable the Instance Lease feature, will be applicable only on instances created after lease is enabled. **Default: false** +instance.lease.scheduler.interval Background task interval in seconds that executes Lease expiry action on eligible expired instances. Default: 3600. +instance.lease.eventscheduler.interval Background task interval in seconds that executes Lease event executor for instances about to be expired in next N days. Default: 86400 +instance.lease.expiryevent.daysbefore Denotes number of days (N) in advance expiry events are generated for instance about to expire. Default: 7 days +======================================= ======================== + +.. note:: it is recommended to configure the lowest possible value (in secs) for **instance.lease.scheduler.interval**, so that lease expiry action is taken as soon as lease is expired. + + +**Lease Parameters** + + +**leaseduration**: Lease duration is specified in days. This can take Natural numbers (>=1) and -1 to disable the lease. Max supported value is 36500 (100 years). + +User can disable Lease for instance in two ways: + +- Disable the Instance Lease during instance deployment by unchecking the 'Enable Lease' option when using a Compute Offering that supports it. +- For existing instances with a lease already enabled, it can be removed by editing the instance and unchecking the 'Enable Lease' option. + +**leaseexpiryaction**: There are two expiry action supported: + +- STOP: The instance is stopped, and it will be out of lease. The user can restart the instance manually. +- DESTROY: The instance is destroyed when the lease expires. + +.. note:: Expiry action is executed at most once on the instance, e.g. STOP action will bring instance in Stopped state on expiry and instance will be out of lease. User may choose to start it again. + + +**Using Instance Lease** + +Lease information is associated to an Instance and following parameters are used to enable lease for it: + +#. leaseduration +#. leaseexpiryaction + +Instance remains active for specified leaseduration (in days). Upon lease expiry, configured expiryaction is executed on the instance and +lease is removed from the instance for any further action. + +**Notes:** + +#. Lease Assignment: A lease can only be assigned to an instance during deployment. +#. Lease Acquisition: Instances without a lease cannot acquire one by switching to a different Compute Offering or by editing the instance. +#. Lease Inheritance: Instances inherit the lease from a Compute Offering with 'Instance Lease' feature enabled. This lease can be overridden or disabled in the “Advanced Settings”. +#. Lease Persistence: A lease is always tied to the instance. Modifications to the Compute Offering do not affect the instance's lease. +#. Non-Lease Compute Offering: Instances can have a lease by enabling it in the "Advanced Settings" for non-lease based Compute Offering too. +#. Lease Duration Management: The lease duration can be extended or reduced for instances before expiry. However, once the lease is disabled, it cannot be re-enabled for that instance. +#. Lease Expiry: Once the lease expires and the associated action is completed, the lease is annulled and cannot be reattached or extended. +#. Feature Disablement: If the lease feature is disabled, the lease associated with instances is canceled. Re-enabling the feature will not automatically reapply the lease to previously grandfathered instances. +#. Delete Protection: The DESTROY lease expiry action is skipped for instances with delete protection enabled. + +**Deployment of Instance with lease** + +There are 2 ways to deploy instance with lease from UI: + +1. Use Compute Offering which has 'Instance Lease' feature enabled. + +.. image:: /_static/images/deploy_instance_lease_offering.png + :width: 400px + :align: center + :alt: Deploy Instance with lease compute offering dialog box + +2. Enable lease under Advance settings during instance Deployment + +.. image:: /_static/images/deploy_instance_advanced_lease.png + :width: 400px + :align: center + :alt: Deploy Instance with lease using advance 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 for users via "user.vm.denied.details" global setting. VM details/settings can also be made read-only for users using "user.vm.readonly.details" global setting. List of default hidden and read-only details/settings is given below. +**Using API** + +Pass lease parameters in the command to enable lease during instance deployment: + +.. code:: bash + + cmk deploy virtualmachine name=..... leaseduration=... leaseexpiryaction=... + +- Use Compute Offering with lease + +.. code:: bash + + cmk deploy virtualmachine name=..... serviceofferingid=lease-compute-offering + + +**Editing Instance Lease** + +The lease duration for an instance can be extended, reduced, or disabled for instances that already have an active lease. +However, it is not possible to enable the lease on an instance after it has already been deployed. + +From UI: + +.. image:: /_static/images/edit_instance_lease.png + :width: 400px + :align: center + :alt: Edit Instance Lease dialog + + +Using API: + +.. code:: bash + + cmk update virtualmachine id=fa970d19-8340-455c-a9fb-569205954fdc leaseduration=20 leaseexpiryaction=DESTROY + +To disable lease using API: + +.. code:: bash + + cmk update virtualmachine id=fa970d19-8340-455c-a9fb-569205954fdc leaseduration=-1 + +.. note:: DESTROY action will ignore instance if deleteprotection is enabled for it. + +.. note:: When the feature is disabled, the lease associated with instances is cancelled. Re-enabling the feature will not automatically reapply the lease to previously grandfathered instances. + +.. note:: Lease duration is considered as total lease for instance. + +**Instance Lease Events** + +Lease feature generates various events to help in auditing and monitoring: + +=================== ======================== +Event Type Description +=================== ======================== +VM.LEASE.EXPIRED Event is generated at lease expiry +VM.LEASE.DISABLED Denotes if lease is disabled by user/admin +VM.LEASE.CANCELLED When lease is cancelled (feature gets disabled) +VM.LEASE.EXPIRING Expiry intimation event for instance +=================== ======================== + + +Advanced Instance Settings +-------------------------- + +Each User Instance has a set of "details" associated with it (as visible via listVirtualMachine API call) - those "details" are shown on the "Settings" tab of the Instance 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 Instance is in a Stopped state. +Some Instance details/settings can be hidden for users via "user.vm.denied.details" global setting. Instance details/settings can also be made read-only for users using "user.vm.readonly.details" global setting. List of default hidden and read-only details/settings is given below. .. note:: - Since version 4.15, VMware VM settings for the ROOT disk controller, NIC adapter type and data disk controller are populated automatically with the values inherited from the template. + Since version 4.15, VMware Instance settings for the ROOT disk controller, NIC adapter type and data disk controller are populated automatically with the values inherited from the Template. 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). @@ -780,114 +1166,209 @@ An example list of settings as well as their possible values are shown on the im |vm-settings-values-dropdown-KVM-list.png| (KVM disk controllers) +|vm-settings-kvm-guest-cpu-model.png| +(KVM guest CPU model, available for root admin since 4.20.1.0) + +CloudStack supports setting the guest machine type for KVM instances since 4.22.0 by using the instance setting 'kvm.guest.os.machine.type'. The list of supported machine types will depend on the QEMU version on the KVM host. + +.. note:: + For Ubuntu 24 KVM hosts (and other distros containing QEMU 8.x versions) setting the machine type for Windows VMs to 'pc-i440fx-8.0' mitigates the issue which prevents retrieving the instance UUID from within the guest VM via: `wmic path win32_computersystemproduct get uuid`. + +Instance Settings for Virtual Trusted Platform Module (vTPM) +----------------------------- + +Trusted Platform Module (TPM) is a standard for a secure cryptoprocessor, which +can securely store artifacts used to authenticate the platform, including passwords, +certificates, or encryption keys. TPM is required by recent Windows releases. + +Virtual Trusted Platform Module (vTPM) is the software-based representation of physical TPM. +CloudStack supports vTPM for instances running on KVM and VMware since 4.20.1.0 . + +|vm-settings-uefi-secure.png| +UEFI setting + +- On Vmware, the boot type must be set to UEFI. Boot mode can be SECURE (recommended) or LEGACY. +- On KVM, it is recommended to set boot type to UEFI, and boot mode to SECURE. +- UEFI is required for some Windows versions. +- On XenServer amd XCP-ng, the boot type must be set to UEFI, boot mode can be SECURE or LEGACY. vTPM is supported on XenServer 8.3 and later versions and XCP-ng 8.4 and later versions. vTPM can be enabled by setting the virtual.tpm.enabled setting on the template or vm instance as done on VMware. +- For XenServer and XCP-ng, to boot Windows VMs in UEFI Secure more, the host needs to have Microsoft UEFI Secure Boot certificates installed. Run `secureboot-certs install` on the host to install them. This makes certificates available to OVFM, QEMU, shim tooling. + +- tpm-tis, TIS means TPM Interface Specification; +- tpm-crb, CRB means Command-Response Buffer. + +|vm-settings-virtual-tpm-version-kvm.png| +TPM version for KVM. There are two options: -Virtual Machine Snapshots -========================= +- 2.0. This is the default TPM version. It is used when version is not specified or invalid. +- 1.2. This is not supported with CRB model. + +|vm-settings-virtual-tpm-enabled-vmware.png| +Enable or disable vTPM for VMware. + +Instance 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 +In addition to the existing CloudStack ability to snapshot individual Instance +volumes, you can take an Instance Snapshot to preserve all the Instance'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 +quick restore of an Instance. For example, you can snapshot an Instance, 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 +restore the Instance to its previous state using the previously saved Instance +Snapshot. + +The Snapshot is created using the hypervisor's native Snapshot facility. +The Instance Snapshot includes not only the data volumes, but optionally also +whether the Instance is running or turned off (CPU state) and the memory +contents. The Snapshot is stored in CloudStack's primary storage. + +Instance Snapshots can have a parent/child relationship. Each successive +Snapshot of the same Instance is the child of the Snapshot that came before +it. Each time you take an additional Snapshot of the same Instance, it saves +only the differences between the current state of the Instance 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 Instance back to the original. -After VM snapshots are created, they can be tagged with a key/value pair, +After Instance 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. +KVM supports Instance Snapshots when using NFS shared storage. If raw block storage +is used (i.e. Ceph), then Instance Snapshots are not possible, since there is no possibility +to write RAM memory content anywhere. In such cases you can use as an alternative +:ref:`Storage-based-Instance-Snapshots-on-KVM`. -If you need more information about VM snapshots on VMware, check out the + +If you need more information about Instance Snapshots on VMware, check out the VMware documentation and the VMware Knowledge Base, especially -`Understanding virtual machine snapshots +`Understanding Instance Snapshots `_. -Limitations on VM Snapshots ---------------------------- +.. _Storage-based-Instance-Snapshots-on-KVM: + +Storage-based Instance Snapshots on KVM +--------------------------------------- + +.. note:: + For now this functionality is limited for NFS and Local storage. + +CloudStack introduces a new Storage-based Instance Snapshots on KVM feature that provides +crash-consistent Snapshots of all disks attached to the Instance. It employs the underlying storage +providers’ capability to create/revert/delete disk Snapshots. Consistency is obtained by freezing +the Instance before the snapshotting. Memory Snapshots are not supported. + +.. note:: + ``freeze`` and ``thaw`` of Instance is maintained by the guest agent. + ``qemu-guest-agent`` has to be installed in the Instance. + +When the snapshotting is complete, the Instance is thawed. + +You can use this functionality on Instances with raw block storages (E.g. Ceph/SolidFire/Linstor). + +.. _Disk-only-File-based-Storage-Instance-Snapshots-on-KVM: + +Disk-only File-based Storage Instance Snapshot on KVM +----------------------------------------------------- + +Since version 4.21, CloudStack supports incremental disk-only instance snapshots for VMs on KVM that are running on file-based storages (NFS, local, shared mount point). +Different from :ref:`Storage-based-Instance-Snapshots-on-KVM`, the VM is not frozen by default; only if the ``quiescevm`` parameter is provided. Furthermore, if ``quiescevm`` is true +the VM is only frozen during the operation of creating the deltas on the volumes of the VM, thus the downtime is minimal. + +When using this snapshot strategy, you will not be able to create volume snapshots, as these two features are not compatible. If you want to use both volume snapshots and instance snapshots +at the same time, you may inform the value ``KvmFileBasedStorageVmSnapshotStrategy`` on the ``vmSnapshot.strategies.exclude`` configuration, so that +this strategy is not used and the :ref:`Storage-based-Instance-Snapshots-on-KVM` feature is used instead. + +More information on this feature may be found in the `specification `_. -- 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 +Limitations on Instance Snapshots +--------------------------------- + +- If an Instance has some stored Snapshots, you can't attach new volume to the + Instance or delete any existing volumes. If you change the volumes on the + Instance, it would become impossible to restore the Instance Snapshot which was created with the previous volume structure. If you want to attach a - volume to such a VM, first delete its snapshots. + volume to such an Instance, 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 +- Instance Snapshots which include both data volumes and memory can't be kept + if you change the Instance's service offering. Any existing Instance 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 can't make an Instance 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 +- You should use only CloudStack to create Instance Snapshots on hosts + managed by CloudStack. Any Snapshots that you make directly on the hypervisor will not be tracked in CloudStack. +Pause During Live Instance Snapshots on KVM +------------------------------------------- -Configuring VM Snapshots ------------------------- +When creating **Instance Snapshots with Memory**, CloudStack uses Libvirt’s +*domain snapshot* API to create an Internal Snapshot that includes Memory. +The guest’s memory state is written directly into the root volume’s QCOW2 file. +This causes the instance to pause for the duration of the memory dump. The pause +time is typically much longer than with VMware snapshots, but this is a limitation +with Internal Snapshots in Libvirt. + +**Instance Snapshots without Memory** has seen significant improvements since Cloudstack 4.21 with the +:ref:`Disk-only-File-based-Storage-Instance-Snapshots-on-KVM` feature for NFS and local storage. +Pre 4.21, the Instance would be frozen for the entire duration of the snapshot create operation. +Since 4.21, the Instance is only frozen during the checkpointing operation, which is significantly less. + +Users looking for the Instance Snapshot feature in KVM are recommended to use the +:ref:`Disk-only-File-based-Storage-Instance-Snapshots-on-KVM` feature, if the pause duration is a concern. +App consistent snapshots can be created by using the ``quiescevm`` parameter with pre and post-freeze hooks. +The Instance should have Qemu Guest Agent installed for this to work. + +Configuring Instance Snapshots +------------------------------ The cloud administrator can use global configuration variables to -control the behavior of VM snapshots. To set these variables, go through +control the behavior of Instance 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. -====================== ======================== +================================= ======================== +Configuration Description +================================= ======================== +vmsnapshots.max The maximum number of Instance Snapshots that can be saved for any given Instance in the cloud. The total possible number of Instance Snapshots in the cloud is (number of Instances) \* vmsnapshots.max. If the number of Snapshots for any Instance 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. +kvm.vmstoragesnapshot.enabled For live Snapshot of an Instance on KVM hypervisor without memory. Requires qemu version 1.6+ (on NFS or Local file system) and qemu-guest-agent installed on guest Instance +================================= ======================== +Using Instance Snapshots +------------------------ -Using VM Snapshots ------------------- - -To create a VM snapshot using the CloudStack UI: +To create an Instance 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 name of the Instance you want to Snapshot. -#. Click the Take VM Snapshot button. |VMSnapshotButton.png| +#. Click the Take Instance Snapshot button. |VMSnapshotButton.png| .. note:: - If a snapshot is already in progress, then clicking this button + 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 +#. Provide a name and description. These will be displayed in the Instance 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. +#. (For running Instances only) If you want to include the Instance's memory in the + Snapshot, click the Memory checkbox. This saves the CPU and memory + state of the Instance. If you don't check this box, then only + the current state of the Instance 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 +#. Quiesce Instance: check this box if you want to quiesce the file system on + the Instance 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, @@ -898,25 +1379,25 @@ To create a VM snapshot using the CloudStack UI: #. Click OK. -To delete a snapshot or restore a VM to the state saved in a particular -snapshot: +To delete a Snapshot or restore an Instance to the state saved in a particular +Snapshot: -#. Navigate to the VM as described in the earlier steps. +#. Navigate to the Instance as described in the earlier steps. -#. Click View VM Snapshots. +#. Click View Instance Snapshots. -#. In the list of snapshots, click the name of the snapshot you want to +#. 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 delete the Snapshot, click the Delete button. |delete-button.png| - To revert to the snapshot, click the Revert button. |revert-vm.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. + Instance Snapshots are deleted automatically when an Instance is destroyed. You don't + have to manually delete the Snapshots in this case. Support for Virtual Appliances @@ -925,14 +1406,32 @@ Support for Virtual Appliances .. include:: virtual_machines/virtual_appliances.rst -Importing and Unmanaging Virtual Machines -========================================= +Importing and Unmanaging Instances +================================== + +In the UI, both unmanaged and managed virtual machines or instances are listed in *Tools > Import-Export Instances* section, selecting: + + .. cssclass:: table-striped table-bordered table-hover + + ==================== ======================== + Source Destination Hypervisor + ==================== ======================== + Unmanaged Instance VMware + ==================== ======================== + + |vm-unmanagedmanaged.png| + .. include:: ./virtual_machines/importing_unmanaging_vms.rst -Virtual Machine Backups (Backup and Recovery Feature) -===================================================== +Importing Virtual Machines From VMware into KVM +=============================================== + +.. include:: ./virtual_machines/importing_vmware_vms_into_kvm.rst + +Instance Backups (Backup and Recovery Feature) +============================================== .. include:: backup_and_recovery.rst @@ -945,22 +1444,22 @@ additional security. You can use the createSSHKeyPair API to generate the SSH keys. Because each cloud user has their own SSH key, one cloud user cannot log -in to another cloud user's instances unless they share their SSH key -files. Using a single SSH key pair, you can manage multiple instances. +in to another cloud user's Instances unless they share their SSH key +files. Using a single SSH key pair, you can manage multiple Instances. Creating an Instance Template that Supports SSH Keys ---------------------------------------------------- -Create an instance template that supports SSH Keys. +Create an Instance Template that supports SSH Keys. -#. Create a new instance by using the template provided by cloudstack. +#. Create a new Instance by using the Template provided by cloudstack. - For more information on creating a new instance, see + For more information on creating a new Instance, see #. Download the cloudstack script from `The SSH Key Gen Script `_ - to the instance you have created. + to the Instance you have created. .. parsed-literal:: @@ -984,18 +1483,36 @@ Create an instance template that supports SSH Keys. chkconfig --add cloud-set-guest-sshkey.in -#. Stop the instance. +#. Stop the Instance. Creating the SSH Keypair ------------------------ -You must make a call to the createSSHKeyPair api method. You can either +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Compute --> SSH Key Pairs. + +#. Click Create a SSH Key Pair. + +#. In the dialog, make the following choices: + + - **Name**: Any desired name for the SSH Key Pair. + + - **Public key**: (Optional) Public key material of the SSH Key Pair. + + .. note:: If this field is filled in, CloudStack will register the public key. If this field is left blank, CloudStack will create a new SSH key pair. + + - **Domain**: (Optional) domain for the SSH Key Pair. + +.. note:: If Cloudstack generates a New SSH Key Pair using a public key, it will not save the private key. When shown, be sure to save a copy of it. + +You can also use the ``createSSHKeyPair`` api method to create an SSH Keypair. You can either use the CloudStack Python API library or the curl commands to make the call to the cloudstack api. For example, make a call from the cloudstack server to create a SSH -keypair called "keypair-doc" for the admin account in the root domain: +keypair called "keypair-doc" for the admin Account in the root domain: .. note:: Ensure that you adjust these values to meet your needs. If you are @@ -1049,23 +1566,23 @@ keypair called "keypair-doc" for the admin account in the root domain: 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 +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 Instance Template that Supports SSH Keys” <#create-ssh-template>`__. Ensure that you use the same SSH key name that you created at `Section 5.2.2, “Creating the SSH Keypair” <#create-ssh-keypair>`__. .. note:: - You cannot create the instance by using the GUI at this time and - associate the instance with the newly created SSH keypair. + You cannot create the Instance by using the GUI at this time and + associate the Instance with the newly created SSH keypair. -A sample curl command to create a new instance is: +A sample curl command to create a new Instance is: .. parsed-literal:: curl --globoff http://localhost:/?command=deployVirtualMachine\&zoneId=1\&serviceOfferingId=18727021-7556-4110-9322-d625b52e0813\&templateId=e899c18a-ce13-4bbf-98a9-625c5026e0b5\&securitygroupids=ff03f02f-9e3b-48f8-834d-91b822da40c5\&account=admin\&domainid=1\&keypair=keypair-doc -Substitute the template, service offering and security group IDs (if you +Substitute the Template, service offering and security group IDs (if you are using the security group feature) that are in your cloud environment. @@ -1089,120 +1606,166 @@ The -i parameter tells the ssh client to use a ssh key found at 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 -compromised SSH keypair can be changed, and the user can access the VM -by using the new keypair. Just create or register a new keypair, then -call resetSSHKeyForVirtualMachine. +A lost or compromised SSH keypair can be changed, and the user can access the Instance by using the new keypair. + +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Compute --> Instances. + +#. Choose the Instance. + +#. Click on Reset SSH Key Pair button the Instance. + + .. note:: The Instance must be in a Stopped state. + +#. Select the SSH Key Pair(s) to add to instance + +.. note:: This can also be performed via API: ``resetSSHKeyForVirtualMachine``: Resets the assigned SSH keypair for an Instance. .. include:: virtual_machines/user-data.rst -Assigning GPU/vGPU to Guest VMs -=============================== +Assigning GPU/vGPU to Guest Instances +===================================== -CloudStack can deploy guest VMs with Graphics Processing Unit (GPU) or Virtual +CloudStack can deploy guest Instances with Graphics Processing Unit (GPU) or Virtual Graphics Processing Unit (vGPU) capabilities on XenServer hosts. At the time of -VM deployment or at a later stage, you can assign a physical GPU ( known as -GPU-passthrough) or a portion of a physical GPU card (vGPU) to a guest VM by -changing the Service Offering. With this capability, the VMs running on +Instance deployment or at a later stage, you can assign a physical GPU ( known as +GPU-passthrough) or a portion of a physical GPU card (vGPU) to a guest Instance by +changing the Service Offering. With this capability, the Instances running on CloudStack meet the intensive graphical processing requirement by means of the high computation power of GPU/vGPU, and CloudStack users can run multimedia rich applications, such as Auto-CAD, that they otherwise enjoy at their desk on a virtualized environment. -CloudStack leverages the XenServer support for NVIDIA GRID Kepler 1 and 2 series -to run GPU/vGPU enabled VMs. NVIDIA GRID cards allows sharing a single GPU cards -among multiple VMs by creating vGPUs for each VM. With vGPU technology, the -graphics commands from each VM are passed directly to the underlying dedicated -GPU, without the intervention of the hypervisor. This allows the GPU hardware -to be time-sliced and shared across multiple VMs. XenServer hosts use the GPU -cards in following ways: - -**GPU passthrough**: GPU passthrough represents a physical GPU which can be -directly assigned to a VM. GPU passthrough can be used on a hypervisor alongside + +For KVM, CloudStack leverages libvirt's PCI passthrough feature to assign a +physical GPU to a guest Instance. For vGPU profiles, depending on the vGPU type, +CloudStack uses mediated devices or Virtual Functions(VF) to assign a virtual +GPU to a guest Instance. It's the responsibility of the operator to ensure that +GPU devices are in correct state and are available for use on the host. If the +operator wants to use vGPU profiles, they need to ensure that the vGPU type is +supported by the host and has been created on the host. + +For XenServer, CloudStack leverages the XenServer support for NVIDIA GRID +Kepler 1 and 2 series to run GPU/vGPU enabled Instances. + +Some NVIDIA cards allow sharing a single GPU card among multiple Instances by +creating vGPUs for each Instance. With vGPU technology, the graphics commands +from each Instance are passed directly to the underlying dedicated GPU, without +the intervention of the hypervisor. This allows the GPU hardware to be +time-sliced and shared across multiple Instances. The GPU cards are used in the +following ways: + +**passthrough**: GPU passthrough represents a physical GPU which can be +directly assigned to an Instance. GPU passthrough can be used on a hypervisor alongside GRID vGPU, with some restrictions: A GRID physical GPU can either host GRID vGPUs or be used as passthrough, but not both at the same time. -**GRID vGPU**: GRID vGPU enables multiple VMs to share a single physical GPU. -The VMs run an NVIDIA driver stack and get direct access to the GPU. GRID +**vGPU**: vGPU enables multiple Instances to share a single physical GPU. +The Instances run an NVIDIA driver stack and get direct access to the GPU. GRID physical GPUs are capable of supporting multiple virtual GPU devices (vGPUs) -that can be assigned directly to guest VMs. Guest VMs use GRID virtual GPUs in +that can be assigned directly to guest Instances. Guest Instances use vGPUs in the same manner as a physical GPU that has been passed through by the -hypervisor: an NVIDIA driver loaded in the guest VM provides direct access to +hypervisor: an NVIDIA driver loaded in the guest Instance provides direct access to the GPU for performance-critical fast paths, and a paravirtualized interface to -the GRID Virtual GPU Manager, which is used for nonperformant management -operations. NVIDIA GRID Virtual GPU Manager for XenServer runs in dom0. +the NVIDIA vGPU Manager, which is used for nonperformant management +operations. NVIDIA vGPU Manager for XenServer runs in dom0. + CloudStack provides you with the following capabilities: -- Adding XenServer hosts with GPU/vGPU capability provisioned by the administrator. +- Adding hosts with GPU/vGPU capability provisioned by the administrator. + (Supports only XenServer & KVM) -- Creating a Compute Offering with GPU/vGPU capability. +- Creating a Compute Offering with GPU/vGPU capability. For KVM, it is possible to + specify the GPU count and whether to use the GPU for display. For XenServer, + GPU count is simply ignored and only one device is assigned to the guest Instance. -- Deploying a VM with GPU/vGPU capability. +- Deploying an Instance with GPU/vGPU capability. -- Destroying a VM with GPU/vGPU capability. +- Destroying an Instance with GPU/vGPU capability. -- Allowing an user to add GPU/vGPU support to a VM without GPU/vGPU support by +- Allowing a user to add GPU/vGPU support to an Instance without GPU/vGPU support by changing the Service Offering and vice-versa. -- Migrating VMs (cold migration) with GPU/vGPU capability. +- Migrating Instances (cold migration) with GPU/vGPU capability. - Managing GPU cards capacity. - Querying hosts to obtain information about the GPU cards, supported vGPU types in case of GRID cards, and capacity of the cards. +- Limit an account/domain/project to use a certain number of GPUs. + Prerequisites and System Requirements ------------------------------------- Before proceeding, ensure that you have these prerequisites: -- The vGPU-enabled XenServer 6.2 and later versions. - For more information, see `Citrix 3D Graphics Pack `_. +- CloudStack does not restrict the deployment of GPU-enabled Instances with + guest OS types that are not supported for GPU/vGPU functionality. The deployment + would be successful and a GPU/vGPU will also get allocated for Instances; however, + due to missing guest OS drivers, Instance would not be able to leverage GPU resources. + Therefore, it is recommended to use GPU-enabled service offering only with supported guest OS. -- GPU/vPGU functionality is supported for following HVM guest operating systems: - For more information, see `Citrix 3D Graphics Pack `_. +- NVIDIA GRID K1 (16 GiB video RAM) AND K2 (8 GiB of video RAM) cards supports + homogeneous virtual GPUs, implies that at any given time, the vGPUs resident on + a single physical GPU must be all of the same type. However, this restriction + doesn't extend across physical GPUs on the same card. Each physical GPU on a + K1 or K2 may host different types of virtual GPU at the same time. For example, + a GRID K2 card has two physical GPUs, and supports four types of virtual GPU; + GRID K200, GRID K220Q, GRID K240Q, AND GRID K260Q. -- Windows 7 (x86 and x64) +- NVIDIA driver must be installed to enable vGPU operation as for a physical NVIDIA GPU. -- Windows Server 2008 R2 -- Windows Server 2012 +For XenServer: -- Windows 8 (x86 and x64) +- the vGPU-enabled XenServer 6.2 and later versions. + For more information, see `Citrix 3D Graphics Pack `_. -- Windows 8.1 ("Blue") (x86 and x64) +- GPU/vGPU functionality is supported for following HVM guest operating systems: + For more information, see `Citrix 3D Graphics Pack `_. -- Windows Server 2012 R2 (server equivalent of "Blue") + - Windows 7 (x86 and x64) -- CloudStack does not restrict the deployment of GPU-enabled VMs with guest OS types that are not supported by XenServer for GPU/vGPU functionality. The deployment would be successful and a GPU/vGPU will also get allocated for VMs; however, due to missing guest OS drivers, VM would not be able to leverage GPU resources. Therefore, it is recommended to use GPU-enabled service offering only with supported guest OS. + - Windows Server 2008 R2 -- NVIDIA GRID K1 (16 GiB video RAM) AND K2 (8 GiB of video RAM) cards supports homogeneous virtual GPUs, implies that at any given time, the vGPUs resident on a single physical GPU must be all of the same type. However, this restriction doesn't extend across physical GPUs on the same card. Each physical GPU on a K1 or K2 may host different types of virtual GPU at the same time. For example, a GRID K2 card has two physical GPUs, and supports four types of virtual GPU; GRID K200, GRID K220Q, GRID K240Q, AND GRID K260Q. + - Windows Server 2012 -- NVIDIA driver must be installed to enable vGPU operation as for a physical NVIDIA GPU. + - Windows 8 (x86 and x64) -- XenServer tools are installed in the VM to get maximum performance on XenServer, regardless of type of vGPU you are using. Without the optimized networking and storage drivers that the XenServer tools provide, remote graphics applications running on GRID vGPU will not deliver maximum performance. + - Windows 8.1 ("Blue") (x86 and x64) -- To deliver high frames from multiple heads on vGPU, install XenDesktop with HDX 3D Pro remote graphics. + - Windows Server 2012 R2 (server equivalent of "Blue") -Before continuing with configuration, consider the following: +- XenServer tools are installed in the Instance to get maximum performance on + XenServer, regardless of type of vGPU you are using. Without the optimized + networking and storage drivers that the XenServer tools provide, remote + graphics applications running on GRID vGPU will not deliver maximum performance. -- Deploying VMs GPU/vGPU capability is not supported if hosts are not available with enough GPU capacity. +- To deliver high frames from multiple heads on vGPU, install XenDesktop with + HDX 3D Pro remote graphics. -- A Service Offering cannot be created with the GPU values that are not supported by CloudStack UI. However, you can make an API call to achieve this. +Before continuing with configuration, consider the following: -- Dynamic scaling is not supported. However, you can choose to deploy a VM without GPU support, and at a later point, you can change the system offering to upgrade to the one with vGPU. You can achieve this by offline upgrade: stop the VM, upgrade the Service Offering to the one with vGPU, then start the VM. +- Deploying Instances with GPU/vGPU capability is not supported if hosts are + not available with enough GPU capacity. -- Live migration of GPU/vGPU enabled VM is not supported. +- Dynamic scaling is not supported. However, you can choose to deploy an + Instance without GPU support, and at a later point, you can change the system + offering to upgrade to the one with vGPU. You can achieve this by offline + upgrade: stop the Instance, upgrade the Service Offering to the one with + vGPU, then start the Instance. -- Limiting GPU resources per Account/Domain is not supported. +- Live migration of GPU/vGPU enabled Instance is not supported. - Disabling GPU at Cluster level is not supported. - Notification thresholds for GPU resource is not supported. -Supported GPU Devices ---------------------- + +Supported GPU Devices for XenServer +----------------------------------- .. cssclass:: table-striped table-bordered table-hover @@ -1225,52 +1788,119 @@ GPU/vGPU Assignment Workflow ----------------------------- -CloudStack follows the below sequence of operations to provide GPU/vGPU support for VMs: +CloudStack follows the below sequence of operations to provide GPU/vGPU support for Instances: -#. Ensure that XenServer host is ready with GPU installed and configured. - For more information, see `Citrix 3D Graphics Pack `_. +#. Ensure that the host is ready with GPU installed and configured. + + - For more information for XenServer, see `XenServer Documentation `_. + + - For KVM, to configure the host see how to `discover GPU Devices on Hosts here `_. #. Add the host to CloudStack. CloudStack checks if the host is GPU-enabled or not. CloudStack queries the host and detect if it's GPU enabled. #. Create a compute offering with GPU/vGPU support: - For more information, see `Creating a New Compute Offering <#creating-a-new-compute-offering>`__.. + For more information, see `Creating a New Compute Offering `_. #. Continue with any of the following operations: - - Deploy a VM. + - Deploy an Instance. - Deploy a VM with GPU/vGPU support by selecting appropriate Service Offering. CloudStack decide which host to choose for VM deployment based on following criteria: + Deploy an Instance with GPU/vGPU support by selecting appropriate Service Offering. CloudStack decide which host to choose for Instance deployment based on following criteria: - Host has GPU cards in it. In case of vGPU, CloudStack checks if cards have the required vGPU type support and enough capacity available. Having no appropriate hosts results in an InsufficientServerCapacity exception. - - Alternately, you can choose to deploy a VM without GPU support, and at a later point, you can change the system offering. You can achieve this by offline upgrade: stop the VM, upgrade the Service Offering to the one with vGPU, then start the VM. - In this case, CloudStack gets a list of hosts which have enough capacity to host the VM. If there is a GPU-enabled host, CloudStack reorders this host list and place the GPU-enabled hosts at the bottom of the list. + - Alternately, you can choose to deploy an Instance without GPU support, and at a later point, you can change the system offering. You can achieve this by offline upgrade: stop the Instance, upgrade the Service Offering to the one with vGPU, then start the Instance. + In this case, CloudStack gets a list of hosts which have enough capacity to host the Instance. If there is a GPU-enabled host, CloudStack reorders this host list and place the GPU-enabled hosts at the bottom of the list. + + - Migrate an Instance. + + CloudStack searches for hosts available for Instance migration, which satisfies GPU requirement. If the host is available, stop the Instance in the current host and perform the Instance migration task. If the Instance migration is successful, the remaining GPU capacity is updated for both the hosts accordingly. + + - Destroy an Instance. + + GPU resources are released automatically when you stop an Instance. Once the destroy Instance 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. + + +Instance Metrics +================ + +Instance statistics are collected on a regular interval (defined by global +setting vm.stats.interval with a default of 60000 milliseconds). +Instance statistics include compute, storage and Network statistics. + +Instance statistics are stored in the database as historical data for a desired time period. These historical statistics then can be retrieved using ``listVirtualMachinesUsageHistory`` API. For system VMs, the same historical statistics can be retrieved using ``listSystemVmsUsageHistory`` API + +Instance statistics retention time in the database is controlled by the global configuration ``vm.stats.max.retention.time``, with a default value of 720 minutes, i.e., 12 hours. The interval in which the metrics are retrieved are defined by the global configuration ``vm.stats.interval``, which has a default value of 60,000 milliseconds, i.e., 1 minute. The default values are only meant for guideline, as they can have a major impact in DB performance. The equation below presents the overall storage size required considering the values of these configurations. + +.. math:: - - Migrate a VM. + StatsSize = (\frac{retention * 60000}{interval}) * nodes * VMs * registrySize - CloudStack searches for hosts available for VM migration, which satisfies GPU requirement. If the host is available, stop the VM in the current host and perform the VM migration task. If the VM migration is successful, the remaining GPU capacity is updated for both the hosts accordingly. +- **StatsSize**: the size, in `bytes`, required for storing the VM stats; +- **retention**: the value of the configuration ``vm.stats.max.retention.time``; +- **interval**: the value of the configuration ``vm.stats.interval``; +- **nodes**: the number of nodes running the management server in the environment; +- **VMs**: the number of running VMs in the environment; +- **registrySize**: the estimated size, in `bytes`, of the registry in the DB; - - Destroy a VM. +Considering the default values of the configurations ``vm.stats.max.retention.time`` and ``vm.stats.interval``, three nodes running the management server, 10,000 running VMs and an estimated registry size of 400 bytes, it would need, approximately, 8 GB of storage to store VM stats. Therefore, the values for these configurations should be changed considering the CloudStack environment, evaluating the required storage and its impact in DB performance. - 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. +Another global configuration that affects Instance statistics is ``vm.stats.user.vm.only``. When set to 'false' stats for system VMs will be collected, otherwise stats collection will be done only for user Instances. + +In the UI, historical Instance statistics are shown in the Metrics tab in an individual Instance view, as shown in the image below. + +|vm-metrics-ui.png| + + +Instance Disk Metrics +--------------- + +Similar to Instance statistics, Instance disk statistics (disk stats) can also be collected on a regular interval (defined by global setting vm.disk.stats.interval with a default value of 0 seconds which disables disk stats collection). Disk stats are collected in form of diskiopstotal, diskioread, diskiowrite, diskkbsread and diskkbswrite. + +Instance disk statistics can also be made to store in the database and the historical statistics can be retrieved using listVolumesUsageHistory API. + +Instance disk statistics retention in the database is controlled by the global configuration - `vm.disk.stats.retention.enabled`. Default value is false, i.e., retention of Instance disk statistics is disabled. Other global configurations that affects Instance disk statistics are: + +- `vm.disk.stats.interval.min` - Minimal interval (in seconds) to report Instance disk statistics. If vm.disk.stats.interval is smaller than this, use this to report Instance disk statistics. + +- `vm.disk.stats.max.retention.time` - The maximum time (in minutes) for keeping disk stats records in the database. The disk stats cleanup process will be disabled if this is set to 0 or less than 0. + +Instance disk statistics are shown in the Metrics tab in an individual volume view, as shown in the image below. + +|vm-disk-metrics-ui.png| + + + +.. note:: + The metrics or statistics for VMs and VM disks in CloudStack depend on the + hypervisor plugin used for each hypervisor. The behavior can vary across + different hypervisors. For instance, with KVM, metrics are real-time + statistics provided by libvirt. In contrast, with VMware, the metrics are + averaged data based on the global configuration parameter + `vmware.stats.time.window` and a lower value for the configuration may help + observe statistics closer to the real-time values. .. |vm-lifecycle.png| image:: /_static/images/vm-lifecycle.png - :alt: Virtual Machine State Model + :alt: Instance State Model +.. |vm-schedule-tab.png| image:: /_static/images/vm-schedule-tab.png + :alt: Instance Schedule Tab +.. |vm-schedule-form.png| image:: /_static/images/vm-schedule-form.png + :alt: Instance Schedule Form .. |VMSnapshotButton.png| image:: /_static/images/VMSnapshotButton.png :alt: button to restart a VPC .. |delete-button.png| image:: /_static/images/delete-button.png .. |EditButton.png| image:: /_static/images/edit-icon.png - :alt: button to edit the properties of a VM + :alt: button to edit the properties of an Instance .. |change-affinity-button.png| image:: /_static/images/change-affinity-button.png - :alt: button to assign an affinity group to a virtual machine. + :alt: button to assign an affinity group to an Instance. .. |ChangeServiceButton.png| image:: /_static/images/change-service-icon.png - :alt: button to change the service of a VM + :alt: button to change the service of an Instance .. |Migrateinstance.png| image:: /_static/images/migrate-instance.png - :alt: button to migrate an instance + :alt: button to migrate an Instance .. |Destroyinstance.png| image:: /_static/images/destroy-instance.png - :alt: button to destroy an instance + :alt: button to destroy an Instance .. |iso.png| image:: /_static/images/iso-icon.png :alt: depicts adding an iso image .. |console-icon.png| image:: /_static/images/console-icon.png @@ -1287,3 +1917,17 @@ CloudStack follows the below sequence of operations to provide GPU/vGPU support :alt: List of possible VMware NIC models .. |vm-settings-values-dropdown-KVM-list.png| image:: /_static/images/vm-settings-values-dropdown-KVM-list.png :alt: List of possible KVM disk controllers +.. |vm-settings-kvm-guest-cpu-model.png| image:: /_static/images/vm-settings-kvm-guest-cpu-model.png + :alt: List of possible KVM guest CPU models +.. |vm-settings-uefi-secure.png| image:: /_static/images/vm-settings-uefi-secure.png + :alt: Set boot type to UEFI and mode to SECURE +.. |vm-settings-virtual-tpm-model-kvm.png| image:: /_static/images/vm-settings-virtual-tpm-model-kvm.png + :alt: List of TPM models for KVM +.. |vm-settings-virtual-tpm-version-kvm.png| image:: /_static/images/vm-settings-virtual-tpm-version-kvm.png + :alt: List of TPM versions for KVM +.. |vm-settings-virtual-tpm-enabled-vmware.png| image:: /_static/images/vm-settings-virtual-tpm-enabled-vmware.png + :alt: Enable vTPM or not for VMware +.. |vm-metrics-ui.png| image:: /_static/images/vm-metrics-ui.png + :alt: VM metrics UI +.. |vm-disk-metrics-ui.png| image:: /_static/images/vm-disk-metrics-ui.png + :alt: VM Disk metrics UI diff --git a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst index d5b0b3b12f..bc197da889 100644 --- a/source/adminguide/virtual_machines/importing_unmanaging_vms.rst +++ b/source/adminguide/virtual_machines/importing_unmanaging_vms.rst @@ -1,7 +1,7 @@ .. 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 + 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 @@ -13,75 +13,80 @@ specific language governing permissions and limitations under the License. -.. note:: This is currently only available for **vSphere** clusters. +About Import Export Instances +----------------------------- -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). +For certain hypervisors, CloudStack supports importing of Instances from Managed Hosts, External Hosts, Local Storage and Shared Storage, into CloudStack. -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.16 onwards, importing of the unmanaged VMs can also be carried out within the UI. +Manage or Unmanage Instances on Managed Hosts +--------------------------------------------- -From ACS 4.15 onwards, administrators are able to unmanage guest virtual machines. +.. note:: This is currently only available for **vSphere** and **KVM** clusters. -In the UI, both unmanaged and managed virtual machines or instances are listed in *Tools > Import-Export Instances* section: - |vm-unmanagedmanaged.png| +As of ACS 4.14, CloudStack has the concept of **unmanaged** Instances. These are Instances that exist on CloudStack +managed hosts, but are not in CloudStack's database and therefore CloudStack cannot control (manage) them in any way. Previously, +such Instances could exist, but CloudStack did not 'see' them (their existence *would* be reported in logs as unrecognised Instances). +From ACS 4.14 onwards, CloudStack is able to list VMware-based unmanaged instances via the listUnmanagedInstances API command and then import (also known as ingest) +those unmanaged Instances via the importUnmanagedInstance API so that they become CloudStack-managed Guest Instances. -Importing Unmanaged Virtual Machines ------------------------------------- +From ACS 4.15 onwards, administrators are able to unmanage VMware-based guest Instances. + +From ACS 4.16 onwards, importing unmanaged Instances can also be done in the UI. + +From ACS 4.19, CloudStack also supports importing KVM-based guest instances. However, this feature is experimental, and only KVM instances which were previously unmanaged, can be imported/become managed again. + +Importing Unmanaged Instances +----------------------------- Use Cases and General Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ability to import VMs allows Cloud operators (both public and private) to onboard new tenants simply and quickly, -with the minimum amount disk IO. But also can be used in disaster recovery scenarios at remote sites (if storage is -replicated) and in the recreation of VMs which have been backed up (part of the code is indeed used in -CloudStack's Backup and Recovery feature). +The ability to import Instances allows Cloud operators to onboard new tenants simply and quickly, +with the minimum amount of disk IO. It can also be used in disaster recovery scenarios at remote sites (if storage is +replicated). -The most complex part of importing VMs is the mapping of an unmanaged VM's networks to CloudStack networks. As an operator -could be importing tens or even hundreds of VMs, a UI for this feature has not been created as yet. +The most complex part of importing Instances is the mapping of an unmanaged Instance's Networks (on the hypervisor level) to CloudStack Networks, as an operator +could be importing tens or even hundreds of Instances. -If the 'destination' network VLAN(s) and the requested service offerings match the existing VM, then the instance can be -imported whilst it is running. If the VLANs or service offerings do not match, then the instance to be imported must be stopped. -Once the instance has been added to CloudStack, starting it through CloudStack will alter the instances settings in line with -those set in the CloudStack DB. +If the 'destination' Network's VLAN(s) and the requested service offerings match the existing VLAN and the CPU/RAM profile of the Instance on the hypervisor level, then the Instance can be +imported while it is running. If the VLANs or service offerings do not match, then the Instance to be imported must be stopped. +Once the Instance has been added to CloudStack, starting it through CloudStack will alter the Instance's settings on the hypervisor in line with +those set in the CloudStack DB (e.g. the Instance might be moved to a different Port Group on vSwitch/dvSwitch, with the corresponding VLAN) -To import instances, it is imagined that a Cloud Provider will: +To import Instances, it is imagined that a Cloud Provider will: -#. List all of the existing networks which the instances to be imported are on. -#. Create corresponding networks in CloudStack -#. Use the listUnmanagedInstances API to create a CSV of instances to be imported. -#. Where required, add metadata to the CSV such as the Account into which each VM is to associated, the network which each VM is to be - attached to, the Compute Offering required for each instance, and the Disk Offering for each disk +#. List/get familiar with all of the existing Networks on which the Instances to be imported are on. +#. Create corresponding Networks in CloudStack (with the same VLANs, as needed) +#. Use the listUnmanagedInstances API to create a CSV of Instances to be imported. +#. Where required, add metadata to the CSV such as the Account to which the imported Instance should belong, the Network to which each Instance should be + attached to, the Compute Offering required for each Instance, and the Disk Offering for each disk. #. Create a script that will loop through the CSV, sending the importUnmanagedInstance API command with the corresponding - parameters for each instance being read from the CSV + parameters for each Instance being read from the CSV + +Using CSV is just an example that would help in the automation of bulk-importing multiple VMs, but it is not mandatory and operators might decide to do it differently. -Listing unmanaged instances +Listing unmanaged Instances --------------------------- -Prerequisites to list unmanaged instances (vSphere) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Prerequisites to list unmanaged Instances (vSphere or KVM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order for CloudStack to list the instances that are not managed by CloudStack on a host/cluster, the host(s) in the vSphere cluster -must have been added to CloudStack. The standard prerequisites for adding a host to CloudStack apply. +In order for CloudStack to list the Instances that are not managed by CloudStack on a host/cluster, the instances must exist on the hosts that are already part to the CloudStack. listUnmanagedInstances API ~~~~~~~~~~~~~~~~~~~~~~~~~~ -This API will list all unmanaged VMs for a given cluster. Optionally, the vSphere name for an existing unmanaged -VM can be given to retrieve VM details. The API will filter all CloudStack managed VMs, and will also filter templates that show up as VMs on vCenter. +This API will list all unmanaged Instances for a given cluster. Optionally, the vSphere name for an existing unmanaged +Instance can be given to retrieve Instance details. The API will filter all CloudStack managed Instances, and will also filter Templates that show up as Instances on vCenter. **Request parameters**: .. parsed-literal:: - **clusterid** (CloudStack UUID of cluster) - - **name** (vSphere instance name) + - **name** (vSphere Instance name) **Response**: @@ -109,15 +114,15 @@ VM can be given to retrieve VM details. The API will filter all CloudStack manag - **vlanid** - **pcislot** - **adaptertype** (when available) - - **ipaddress** (Only returned when VMware tools are running on instance) + - **ipaddress** (Only returned when VMware tools are running on Instance) Importing Unmanaged Instances ----------------------------- -Administrators can import unmanaged instances either using UI or with the importUnmanagedInstance API. +Administrators can import unmanaged Instances either using UI or with the importUnmanagedInstance API. -UI provides the following form for importing the instance when *Import Instance* action is used in *Import-Export Instances* view: +UI provides the following form for importing the Instance when *Import Instance* action is used in *Import-Export Instances* view: |ImportInstance.png| @@ -128,22 +133,22 @@ importUnmanagedInstance API .. parsed-literal:: - **clusterid** (CloudStack UUID of cluster) - - **name** (vSphere instance name) + - **name** (vSphere Instance name) - **displayname** - **hostname** - - **account** (An optional account name for the virtual machine. Must be used with domainid parameter) - - **domainid** (An optional domain ID for the virtual machine. Must be used with account parameter) + - **account** (An optional account name for the Instance. Must be used with domainid parameter) + - **domainid** (An optional domain ID for the Instance. Must be used with account parameter) - **projectid** - **templateid** - **serviceofferingid** - **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) + - **details** (Map for Instance details) + - **migrateallowed** (Instance and its volumes are allowed to migrate to different host/storage pool when offering tags conflict with host/storage pool) + - **forced** (If true, an Instance 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. +.. note:: The `forced` parameter is false by default and thus prevents importing an Instance which has a NIC containing a MAC address that has been previously assigned by CloudStack to another existing VM. If it is set to true, importing a VM with such already-used MAC addresses of the NICS will be allowed, however, the original MAC address will be replaced with a newly generated MAC address. **Response**: @@ -155,20 +160,20 @@ importUnmanagedInstance API Prerequisites to Importing Unmanaged Instances (vSphere) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are a few prerequisites to importing unmanaged instances into CloudStack. Largely these are simply that the networks which you are going to -attach the instance in CloudStack need to already exist in CloudStack also the storage which an unmanaged instance is on (before importing) and -also the storage which you wish the instance to be on after importing must already have been added to CloudStack. +There are a few prerequisites to importing unmanaged Instances into CloudStack. Largely, these are simply that the network which you are going to +attach the Instance to in CloudStack need to already exist in CloudStack and also that the storage which an unmanaged Instance is located on (before importing) and +also the storage which you wish the Instance to be on after importing (if different from the original storage) must already have been added to CloudStack as Primary Storage pools. -VMs can be imported to isolated, shared or L2 networks. VMs can also be imported and then automatically migrated to storage in accordance with +Instances can be imported to isolated, shared or L2 networks. Instances can also be imported and then automatically migrated to storage in accordance with service offerings using the *migrateallowed* API parameter. Dummy Template ############## -The assumption that all guest instances in CloudStack are created from a template or ISO is hardcoded into CloudStack. This *source* template will -not exist for instances which have been imported into CloudStack, there for a dummy template has been created in the CloudStack database. When a -template ID is not supplied when importing the instance, the built-in dummy template ID will be used. As this template is only a dummy one, it will -not be possible to 'revert' to the original template unless you specify a **real** template ID. +The assumption that all Guest Instances in CloudStack are created from a Template or ISO is hardcoded into CloudStack. This *source* Template will +not exist for Instances which have been imported into CloudStack, there for a dummy Template has been created in the CloudStack database. When a +Template ID is not supplied when importing the Instance, the built-in dummy Template ID will be used. As this Template is only a dummy one, it will +not be possible to 'revert' to the original Template unless you specify a **real** Template ID. Offerings and Automatic Mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -179,28 +184,28 @@ Compute Offerings **Custom vs Fixed Offerings** ''''''''''''''''''''''''''''' -All guest instances in CloudStack must have an associated compute offering. The import API supports using 'fixed' (ie 2 vCPUs with 2GB RAM +All Guest Instances in CloudStack must have an associated compute offering. The import API supports using 'fixed' (ie 2 vCPUs with 2GB RAM hardcoded into the offering) and 'custom' (user can choose the number of vCPUs and memory) offerings. When a custom offering is chosen, -then the CloudStack will automatically set the number vCPUs, CPU speed and amount of RAM, to be the same as the VM before importing it. When -using custom offerings, the instance to be imported can remain running. If the compute offering is 'fixed' and it matches the vCPU and RAM -of the existing instance, the instance can remain running while being imported, otherwise the instance must be stopped first and it will be +then the CloudStack will automatically set the number vCPUs, CPU speed and amount of RAM, to be the same as the Instance before importing it. When +using custom offerings, the Instance to be imported can remain running. If the compute offering is 'fixed' and it matches the vCPU and RAM +of the existing Instance, the Instance can remain running while being imported, otherwise the Instance must be stopped first and it will be reconfigured with the new values when it is started. -For maximum compatibility when importing a VM, the *Custom Constrained* type of compute offerings in CloudStack are the recommended type of -offerings. The amount of memory and number of CPUs assigned to the imported VM will automatically be matched to the existing VM, while the CPU -speed will have been set to a sensible value by the admin when creating the offering. +For maximum compatibility when importing an Instance, the *Custom Constrained* type of compute offerings in CloudStack are the recommended type of +offerings. The amount of memory and number of CPUs assigned to the imported Instance will automatically be matched to the existing Instance, while +the CPU speed will have been set to a sensible value by the admin when creating the offering. .. note:: - To use Custom Unconstrained type of compute offering, CPU speed will need to be passed using details parameter when the CPU reservation is not set for - the unmanaged VM in vSphere. CPU speed in the latter case can be passed as, details[0].cpuSpeed=SOME_VALUE. + To use the Custom Unconstrained type of compute offering, CPU speed will need to be passed using details parameter when the CPU reservation is not set for + the unmanaged Instance in vSphere. CPU speed in the latter case can be passed as, details[0].cpuSpeed=SOME_VALUE. Disk Offerings ############### -To import a VM which has data disks attached, a map of the disk ID and corresponding disk offering ID must be passed via the *datadiskofferinglist* parameter. +To import an Instance which has data disks attached, a map of the disk ID and corresponding disk offering ID must be passed via the *datadiskofferinglist* parameter. For example: @@ -215,30 +220,30 @@ Host and Storage Tags ##################### When the **migrateallowed** parameter is set to true, if the host or storage tags in the compute/disk offerings are incompatible with the current host and/or -storage pool(s), CloudStack will migrate the VM and its volumes to a suitable host and storage pool. +storage pool(s), CloudStack will migrate the Instance and its volumes to a suitable host and storage pool. When **migrateallowed** is false and there is a conflict, an appropriate error will be returned. -Migration is supported for both running and stopped VMs. Live-migration is supported for running imported VM. When a stopped VM is imported, CloudStack will migrate -VM to a suitable host when it is restarted. +Migration is supported for both running and stopped Instances. Live-migration is supported for running imported Instance. When a stopped Instance is imported, CloudStack +will migrate it to a suitable host when it is restarted. -For volumes, live-migration will be carried out for the volumes of a running VM. As per existing CloudStack behaviour, a stopped -imported VM may not appear in vCenter when its root volume is migrated until the VM is restarted. +For volumes, live-migration will be carried out for the volumes of a running Instance. As per existing CloudStack behaviour, a stopped +imported Instance may not appear in vCenter when its root volume is migrated until the Instance is restarted. Networks ######## -When importing an instance, CloudStack needs to attach the virtual network interfaces (vNICs) to CloudStack networks. +When importing an Instance, CloudStack needs to attach the virtual network interfaces (vNICs) to CloudStack networks. vNICs are associated with a network in one of two ways. #. Automatically (available for L2 and shared networks) -#. Manual assignment of vNIC to network (ID) as a map if a VM has more that one NIC +#. Manual assignment of vNIC to network (ID) as a map if an Instance has more that one NIC In an enterprise, the vast majority of networks will operate as *Layer 2* networks with IP addressing handled by an IPAM system such as Active Directory -or InfoBlox. This makes CloudStack's L2 networks the natural choice for a like-for-like migration/on-boarding of VMs. +or InfoBlox. This makes CloudStack's L2 networks the natural choice for a like-for-like migration/on-boarding of Instances. -When importing an instance to a shared or L2 network, CloudStack will automatically look for a CloudStack network that has the same VLAN(s) as the instance's NIC(s) -is already on. This can be overridden by providing a network_id for the **'nicnetworklist'** parameter +When importing an Instance to a shared or L2 network, CloudStack will automatically look for a CloudStack network that has the same VLAN(s) as the Instance's NIC(s) +is already on. This can be overridden by providing a network_id for the **'nicnetworklist'** parameter .. note:: this includes PVLANs on L2 networks. @@ -247,63 +252,63 @@ IP Addresses '''''''''''' To assigning a specific IP address to a NIC, the **'nicipaddresslist'** parameter is used. This parameter should not be used for L2 networks, and is optional for shared networks. -To ask CloudStack to assign an instance's existing IP when importing, a value of `auto` can be used. +To ask CloudStack to assign an Instance's existing IP when importing, a value of `auto` can be used. .. parsed-literal:: nicipaddresslist[0].nic=NIC_ID nicipaddresslist[0].ip4Address=auto -Auto-assigning IP addresses requires VMware tools to be on the guest instance (for the IP to be reported to vCenter) and is not supported if an unmanaged VM reports more than one IP -address associated with its NIC (CloudStack cannot tell which is the primary address). For instances with more than 1 IP addresses per NIC, pass the first IP address via the import API +Auto-assigning IP addresses requires VMware tools to be on the Guest Instance (for the IP to be reported to vCenter) and is not supported if an unmanaged Instance reports more than one IP +address associated with its NIC (CloudStack cannot tell which is the primary address). For Instances with more than 1 IP addresses per NIC, pass the first IP address via the import API and then add secondary addresses via the **'addIpToNic**' API Registered Operating System ########################### -Import API will try to recognize and map the operating system type for the unmanaged VM to the one from the list of the guest operating systems available in CloudStack. -If the operating system type can not be mapped, the API will return an error, and the templateid parameter (value = ID of a template with the appropriate operating system) -will be needed for a successful import. When `templateid` is defined in the import API call, the guest operating system details of the imported VM will be set to the -operating system details of the specified template after VM restart. +Import API will try to recognize and map the operating system type for the unmanaged Instance to the one from the list of the guest operating systems available in CloudStack. +If the operating system type can not be mapped, the API will return an error, and the templateid parameter (value = ID of a Template with the appropriate operating system) +will be needed for a successful import. When `templateid` is defined in the import API call, the guest operating system details of the imported Instance will be set to the +operating system details of the specified Template after Instance restart. Other notes for the importUnmanagedInstance API ################################################ -- The API will use **name** for the **hostname** of the VM when hostname parameter is not explicitly passed. +- The API will use **name** for the **hostname** of the Instance when hostname parameter is not explicitly passed. The **hostname** cannot be longer than 63 characters. Only ASCII letters a-z, A-Z, digits 0-9, hyphen are allowed. Must start with a letter and end with a letter or a digit. -- NIC adapters and disk controllers of the VM will remain same as they were before the import, irrespective of the template configurations. +- NIC adapters and disk controllers of the Instance will remain same as they were before the import, irrespective of the Template configurations. -- When the VM operating system is automatically recognized during the import (i.e. templateid parameter is not specified), and the operating system of the VM +- When the Instance operating system is automatically recognized during the import (i.e. templateid parameter is not specified), and the operating system of the Instance (as reported by the hypervisor) can be matched to multiple operating systems in the CloudStack, the first match will be used as the operating system for the - imported VM in CloudStack. An example of this is i.e. “CentOS 7 (64-bit)” operating system type, as visible in vSphere, since this one can be matched against + imported Instance in CloudStack. An example of this is i.e. “CentOS 7 (64-bit)” operating system type, as visible in vSphere, since this one can be matched against “CentOS 7” or “CentOS 7.1” or “CentOS 7.2” in CloudStack (based on the existing guest OS mappings), - and here the first one (“CentOS 7”) will be used as the operating system for the imported VM. + and here the first one (“CentOS 7”) will be used as the operating system for the imported Instance. -- Importing VMs with different types of disk controllers for data disks and multiple NICs of different types is not supported and will result in an error response. +- Importing Instances with different types of disk controllers for data disks and multiple NICs of different types is not supported and will result in an error response. Root disk and other (data disks) disks can have different type of controller. -- After import, once the VM is started from CloudStack its CPU and RAM configuration, including CPU limits, CPU reservations, memory reservation, etc. may change from +- After import, once the instance is started from CloudStack its CPU and RAM configuration, including CPU limits, CPU reservations, memory reservation, etc. may change from the original configuration, since all those properties are now controlled by CloudStack (i.e. by cluster-level settings and Compute Offering settings). -- After importing a running VM, the VM will need to be stopped and started (not restarted) via CloudStack to be able to access the console of a VM. +- After importing a running instance, it will need to be stopped and started (not restarted) via CloudStack to be able to access the console of an instance. Discovery of Existing Networks (for vSphere) -------------------------------------------- -To import existing VMs, the networks that they are attached to need to already exist as CloudStack networks. As an existing environment can have a great many networks which +To import existing instances, the networks that they are attached to need to already exist as CloudStack networks. As an existing environment can have a great many networks which need creating, A Python 3 script has been created to enumerate the existing networks. The script (discover_networks.py) can be found in the vm/hypervisor/vmware directory in the CloudStack scripts install location. For most operating systems, CloudStack installs scripts in /usr/share/cloudstack-common/. The script leverages VMware’s pyvmomi library (https://github.com/vmware/pyvmomi). The script lists all networks -for a vCenter host or cluster which have at least one virtual machine attached to them. The script will iterate through these networks and will report the following parameters for them: +for a vCenter host or cluster which have at least one Instance attached to them. The script will iterate through these networks and will report the following parameters for them: - **cluster** (vCenter Cluster belongs to) - **host** (vCenter Host belongs to) - **portgroup** (Portgroup of the network) - **switch** (Switch to which network is connected) -- **virtualmachines** (Virtual machines that are currently connected to the network along with their NIC device details) +- **virtualmachines** (Instances that are currently connected to the network along with their NIC device details) - **vlanid** (VLAN ID of the network) The script can take the following arguments: @@ -329,77 +334,273 @@ The output of this script can then be used in conjunction with the **'createNetw successful import. -Unmanaging Virtual Machines ---------------------------- +Unmanaging Instances +-------------------- + +Administrators can unmanage guest Instances from CloudStack. Once unmanaged, CloudStack can no longer monitor, control or administer the provisioning and orchestration-related operations on an Instance. + +To unmanage a guest Instance, an administrator must either use the UI or invoke the unmanageVirtualMachine API passing the ID of the Instance to unmanage. + +.. code:: bash + + cmk unmanage virtualmachine id= + +The API supports the `hostid` parameter for stopped instances on the KVM hypervisor, allowing the domain XML to be persisted on the specified host. + +.. code:: bash -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. + cmk unmanage virtualmachine id= hostid= -To unmanage a guest virtual machine, an administrator must either use the UI or invoke the unmanageVirtualMachine API passing the ID of the virtual machine to unmanage. The API has the following preconditions: +.. note:: + Instances with Config Drive cannot be unmanaged by default, as the Config Drive ISO will be removed during the unmanage operation. To unmanage such instances via the API, use the forced=true parameter. + +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 Instance must not be destroyed +- The Instance state must be 'Running’ or ‘Stopped’ +- The Instance must be a VMware Instance (as of CloudStack 4.19, it's also possible to unmanage a KVM-based Instances) 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 +- There are no Volume Snapshots associated with any of the Instance volumes +- There is no ISO attached to the Instance -In the UI, *Unmanage VM* action can be used in virtual machine view. |UnmanageButton.png| +In the UI, *Unmanage instance* action can be used in the Instance view. |UnmanageButton.png| Alternately, the same operation can also be carried out using *Unmanage Instance* action in *Import-Export Instances* view under the *Tools* section. |UnmanageInstance.png| -Preserving unmanaged virtual machine NICs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Preserving unmanaged Instance 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. +The zone setting: unmanage.vm.preserve.nics can be used to preserve Instance NICs and its MAC addresses after unmanaging them. If set to true, the Instance NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned. -Unmanaging virtual machine actions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Persistent KVM Domain XML for Unmanaged Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since 4.22, the domain XML of an Instance is made persistent when it is unmanaged from CloudStack. This allows the Instance to be managed directly outside of CloudStack using `virsh` or other libvirt tools. The domain XML will be stored in the directory `/etc/libvirt/qemu` on the relevant KVM host. + +Domain XML is taken from Instance but varies based on their state: + +- Running Instance + - The existing domain XML is retrieved from the Instance and persisted on the host where the Instance is running. +- Stopped Instance + - The domain XML is reconstructed from the Instance details available in the CloudStack database. + - The reconstructed domain XML is persisted on the last host where the Instance was running before it was stopped. If that host is no longer available, the domain XML is saved on any other available host within the cluster. + +.. note:: + It is recommended to unmanage Instances while they are in the **Running** state to ensure that the exact domain XML is preserved. When unmanaged in the **Stopped** state, some information may be lost due to reconstruction. -- Clean up virtual machine NICs and deallocate network resources used such as IP addresses and DHCP entries on virtual routers. + +Unmanaging Instance actions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Clean up Instance 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 Instance 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 Instance Snapshots in the CloudStack database (if any) +- Revoke host access to any managed volumes attached to the instance (applicable to managed storage only) -- Clean up the virtual machine from the following: +- Clean up the Instance from the following: - - Remove the virtual machine from security groups (if any) + - Remove the Instance from security groups (if any) - - Remove the virtual machine from instance groups (if any) + - Remove the Instance from instance groups (if any) - - Remove firewall rules for the virtual machine (if any) + - Remove firewall rules for the Instance (if any) - - Remove port forwarding rules for the virtual machine (if any) + - Remove port forwarding rules for the Instance (if any) - - Remove load balancing rules for the virtual machine (if any) + - Remove load balancing rules for the Instance (if any) - - Disable static NAT (if the virtual machine is assigned to it) + - Disable static NAT (if the Instance is assigned to it) - - Remove the virtual machine from affinity groups (if any) + - Remove the Instance from affinity groups (if any) -- Remove VM details from the CloudStack database +- Remove instance details from the CloudStack database -- Decrement the account resources count for volumes and virtual machines +- Decrement the account resources count for volumes and Instances - 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 Instance Snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ and 'VMSNAPSHOT.OFF_PRIMARY' + + - For Instance NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’ + + - For the Instance being unmanaged: stopped and destroyed usage events (similar to the generated usage events when expunging an Instance), with types: ‘VM.STOP’ and ‘VM.DESTROY', unless the instance has been already stopped before being unmanaged and in this case only ‘VM.DESTROY' is generated. + +Import Instances from External Hosts +------------------------------------ + +.. note:: This is currently only available for **KVM** hypervisor. + +External Host +~~~~~~~~~~~~~ + +An External Host refers to a host that is not managed by CloudStack. The "Import from external host" feature enables importing/migrating +instances from these external hosts. This feature is available in both UI and API. + +Prerequisites +~~~~~~~~~~~~~ +- Ensure that the External KVM host are running libvirt +- Allow libvirt TCP connections (listen_tcp=1) on those External Hosts from CloudStack hosts. +- Instances on the external host have to be in a stopped state, as live migration of instances is not supported +- For some guest operating systems, it's also required that the operating system inside the Instance has been gracefully shut down. +- Currently, it's supported to only use NFS and Local storage as the destination Primary Storage pools in CloudStack +- Currently, only libvirt-based instances can be migrated - - For virtual machine NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’ +.. note:: + - Allocate a NIC to any instance without one immediately after importing it into CloudStack. + - Instances imported on a Config Drive network must be stopped and started after import to properly attach the Config Drive ISO. + +listVmsForImport API +~~~~~~~~~~~~~~~~~~~~ + +listVmsForImport API serves the purpose of listing all +instances currently in a stopped state on the designated External KVM host. Linux user's username and password are needed for this API call and +those same credentials are later used for SSH authentication when the QCOW2 images are moved to the destination CloudStack storage pools + +**Request parameters**: - - 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. +.. parsed-literal:: + - **zoneid** (Zone to which Instance will be imported) + - **host** (the host name or IP address of External Host) + +**Response**: + +.. parsed-literal:: + - **name** + - **osdisplayname** + - **memory** + - **powerstate** + - **cpuCoresPerSocket** + - **cpunumber** + - **cpuspeed** + - **disk** + - **id** + - **capacity** (in bytes) + - **controller** + - **controllerunit** + - **imagepath** + - **position** + - **nic** + - **id** + - **macaddress** + - **networkname** + - **vlanid** + - **pcislot** + - **adaptertype** (when available) + - **ipaddress** + + +importVm API +~~~~~~~~~~~~ + +importVm API invokes the import/migration of the instance (it's disks). Instance's volumes are first converted to the QCOW2 file on the remote host, +and then copied over via SSH to the CloudStack pool. + +The conversion of existing disk images of the Instance on a remote host, to a QCOW2 format is handled by the qemu-img utility. Administrators can +choose the temporary storage location on the external host for the converted file, with the default location set to /tmp. + +**Request parameters**: + +.. parsed-literal:: + - **zoneid** (Zone to which Instance will be imported) + - **host** (the host name or IP address of External Host) + - **username** (the username of External Host for authentication) + - **password** (the password of External Host for authentication) + - **importsource** (Import source should be external) + - **tmppath** (Temp Path on external host for disk image copy) + - **name** (Instance name on External Host) + - **displayname** + - **hostname** + - **account** (An optional account name for the Instance. Must be used with domainid parameter) + - **domainid** (An optional domain ID for the Instance. Must be used with account parameter) + - **projectid** + - **serviceofferingid** + - **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 Instance details) + - **forced** (If true, an Instance is imported despite some of its NIC's MAC addresses being already present) + +.. note:: The `forced` parameter is false by default and thus prevents importing an Instance which has a NIC containing a MAC address that has been previously assigned by CloudStack to another existing VM. If it is set to true, importing a VM with such already-used MAC addresses of the NICS will be allowed, however, the original MAC address will be replaced with a newly generated MAC address. + +**Response**: + +.. parsed-literal:: + Same response as that of deployVirtualMachine API. + +Import Instances from Local/Shared Storage +------------------------------------------ + +.. note:: This is currently only available for **KVM** hypervisor. + +This feature enables an operator to create an Instance using an already-existing QCOW2 image on a Local or Shared Storage pool (NFS only) +in CloudStack. The selected disk image should not be actively in use by any existing volume. The disk image must be in the QCOW2 format. + +QCOW2 files have to already exist on the chosen Local/Shared storage pool - QOCW2 files are not moved/migrated in any way - i.e. they +are expected to already exist on the path as defined when creating an Instance using this feature. + +Import Instances from Local Storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The importVm API is utilized to create instances using QCOW2 file from an existing Local Storage pool of a managed KVM host within the CloudStack infrastructure. + +**Request parameters**: + +.. parsed-literal:: + - **zoneid** (Zone to which Instance will be imported) + - **hostid** (Host where disk image is located) + - **importsource** (Import source should be local) + - **diskpath** (Path of the disk image relative to local storage pool path) + - **name** (Instance name on External Host) + - **displayname** + - **hostname** + - **account** (An optional account name for the Instance. Must be used with domainid parameter) + - **domainid** (An optional domain ID for the Instance. Must be used with account parameter) + - **projectid** + - **serviceofferingid** + +**Response**: + +.. parsed-literal:: + Same response as that of deployVirtualMachine API. + +Import Instances from Shared Storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The importVm API is utilized to create instances using QCOW2 file from an existing Shared Storage pool of a KVM cluster within the CloudStack infrastructure. +Only NFS Storage Pool are supported. + +**Request parameters**: + +.. parsed-literal:: + - **zoneid** (Zone to which Instance will be imported) + - **poolid** (Shared Storage Pool where disk image is located) + - **importsource** (Import source should be shared) + - **diskpath** (Path of the disk image relative to Shared storage pool path) + - **name** (Instance name on External Host) + - **displayname** + - **hostname** + - **account** (An optional account name for the Instance. Must be used with domainid parameter) + - **domainid** (An optional domain ID for the Instance. Must be used with account parameter) + - **projectid** + - **serviceofferingid** + +**Response**: + +.. parsed-literal:: + Same response as that of deployVirtualMachine API. .. |br| raw:: html @@ -413,7 +614,7 @@ Unmanaging virtual machine actions :alt: Unmanaged and Managed Instances. :width: 600 px .. |UnmanageButton.png| image:: /_static/images/unmanage-instance-icon.png - :alt: button to unmanage a VM + :alt: button to unmanage an instance .. |UnmanageInstance.png| image:: /_static/images/vm-unmanage-instance.png - :alt: button to unmanage a VM + :alt: button to unmanage an instance :width: 600 px diff --git a/source/adminguide/virtual_machines/importing_vmware_vms_into_kvm.rst b/source/adminguide/virtual_machines/importing_vmware_vms_into_kvm.rst new file mode 100644 index 0000000000..84848fed26 --- /dev/null +++ b/source/adminguide/virtual_machines/importing_vmware_vms_into_kvm.rst @@ -0,0 +1,204 @@ +.. 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. + +.. note:: This functionality requires **virt-v2v** (https://www.libguestfs.org/virt-v2v.1.html) binary installed on destination cluster hosts (needs to be installed manually as it's not a dependency of the CloudStack agent during the agent installation). + +Requirements on the KVM hosts +----------------------------- + +The CloudStack agent does not install the virt-v2v binary as a dependency. The virt-v2v binary must be installed manually on KVM hosts, or the migration will fail. + +The virt-v2v output (progress) is logged in the CloudStack agent logs, to help administrators track the progress on the Instance conversion processes. The verbose mode for virt-v2v can be enabled by adding the following line to /etc/cloudstack/agent/agent.properties and restart cloudstack-agent: + + :: + + dnf install virt-v2v + + echo "virtv2v.verbose.enabled=true" >> /etc/cloudstack/agent/agent.properties + + systemctl restart cloudstack-agent + + +Installing virt-v2v on Ubuntu KVM hosts does not install nbdkit which is required in the conversion of VMware VCenter guests. To install it, please execute: + + :: + + apt install nbdkit + + +Supported Distributions for KVM Hypervisor: + + +.. cssclass:: table-striped table-bordered table-hover + +======================== ======================== +Linux Distribution Supported Versions +======================== ======================== +Alma Linux 8, 9 +Red Hat Enterprise Linux 8, 9 +Rocky Linux 8, 9 +Ubuntu 22.04 LTS, 24.04 LTS +======================== ======================== + + +Importing Windows VMs from VMware requires installing the virtio drivers for Windows on the hypervisor hosts for the virt-v2v conversion. + +On (RH)EL hosts: + + :: + + yum install virtio-win + +You can also install the RPM manually from https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.noarch.rpm + + +For Debian-based distributions: + +Ubuntu don’t seem to ship the virtio-win package with drivers, which causes virt-v2v not to convert the VMWare Windows guests to virtio profiles. This could result in slow IDE drives and Intel E1000 NICs. As a workaround, we can follow the below steps to install the package from the RPM on all KVM hosts running the virt-v2v: + + :: + + apt install virtio-win (if the package is not available, then manual steps will be required to install the virtio drivers for windows) + + wget https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.noarch.rpm + + # install “alien” which can convert rpms to debs + apt -y install alien + + # the conversion, can take a while + alien -d virtio-win.noarch.rpm + + # install the resulting deb + dpkg -i virtio-win*.deb + +In addition to this, we need to install the below package as well to avoid the error “virt-v2v: error: One of rhsrvany.exe or pvvxsvc.exe is missing in /usr/share/virt-tools“. + + :: + + wget -nd -O srvany.rpm https://kojipkgs.fedoraproject.org//packages/mingw-srvany/1.1/4.fc38/noarch/mingw32-srvany-1.1-4.fc38.noarch.rpm + + alien -d srvany.rpm + + dpkg -i *srvany*.deb + + +The OVF tool (ovftool) must be installed on the destination KVM hosts if the hosts should export VM files (OVF) from vCenter. If not, the management server exports them (the management server doesn't require ovftool installed). + +Steps to install ovftool + +Download the ovftool from https://developer.broadcom.com/tools/open-virtualization-format-ovf-tool/latest + + :: + + unzip VMware-ovftool-4.6.3-24031167-lin.x86_64.zip -d /usr/local/ + + #create a soft link + + ln -s /usr/local/ovftool/ovftool /usr/local/bin/ovftool + +If you are hitting the following error when running ovftool, install the dependecy + +./ovftool.bin: error while loading shared libraries: libnsl.so.1: cannot open shared object file: No such file or directory + + :: + + dnf install libnsl + + +Usage +----- + +In the UI, Virtual Machines to import from VMware are listed in *Tools > Import-Export Instances* section, selecting: + +.. cssclass:: table-striped table-bordered table-hover + +==================================================== ================================= +Select Import-Export Source Hypervisor Action +==================================================== ================================= +VMware Migrate existing instances to KVM +==================================================== ================================= + +|import-vm-from-vmware-to-kvm.png| + +Selecting the Destination cluster +--------------------------------- + +CloudStack administrators must select a KVM cluster to import the VMware Virtual Machines (right side of the image above). Once a KVM cluster is selected, the VMware Datacenter selection part is displayed. + +Selecting the VM from a VMware Datacenter +----------------------------------------- + +CloudStack administrators must select the Source VMware Datacenter: + + - Existing: The existing zones are listed, and for each zone, CloudStack will list if there is any VMware Datacenter associated with it. In case it is, it can be selected. + - External: CloudStack allows listing Virtual Machines from a VMware Datacenter that is not associated with any CloudStack zone. To do so, the vCenter IP address, the datacenter name, and username and password credentials are needed to log in to the vCenter. To import from a standalone VMware host, you can use the default datacenter name (ha-datacenter or other) along with the host credentials (Only stopped VMs are supported). + +Once the VMware Datacenter is selected, click on List VMware Instances to display the list of Virtual Machines in the Datacenter. You must then choose the VMware Instance for import and click on Import Instance. + +Converting and importing a VMware VM +------------------------------------ + +.. note:: CloudStack allows importing Running Linux Virtual Machines, but it is generally recommended that the Virtual Machine to import is powered off and has been gracefully shut down before the process starts. In case a Linux VM is imported while running, it will be converted in a "crash consistent" state. For Windows Virtual Machines, it is not possible to import them while running, they must be shut down gracefully so the filesystem is in a clean state. + +.. note:: You can configure the parallel import of VM disk files on KVM host and management server, using the global settings: threads.on.kvm.host.to.import.vmware.vm.files and threads.on.ms.to.import.vmware.vm.files respectively. + +In the UI import wizard, you can optionally select a KVM host and temporary destination storage (default is Secondary Storage, but if using Primary Storage - only NFS pools are supported) for the conversion, where VM files (OVF) will be copied to. This can be done by a random (or explicitly chosen) KVM host (if the ovftools are installed), otherwise, the management server will export/copy the VM files (optionally, you can force this action to be done by the management server even the KVM hosts have the ovftools installed in it). Irrelevant if the KVM host or the management server performs the copy of the VM files (OVF), you can further either let CloudStack choose which KVM host should do the conversion of the VM files using virt-v2v and which host will import the files to the destination Primary Storage Pool, or you can explicitly choose these KVM hosts for each of the 2 mentioned operations. + +|import-vm-from-vmware-to-kvm-options.png| + +When importing an instance from VMware to KVM, CloudStack performs the following actions: + + - Export the VM files (OVF) of the instance to a temporary storage location + (which can be selected by the administrator). The export is performed by a + KVM host if ovftool is installed or management server (can be forced by the + administrator, doesn't need ovftool installed on the management server). + The existence of ovftool on KVM host is checked using + ``ovftool --version`` command. + + - If the instance on VMware is in **running** state, we clone the instance on + VMware and use the new cloned instance to export OVF files. + The cloning process may take some time to complete and is used to ensure data consistency, + disk consolidation, etc. + - If the instance on VMware is in **stopped** state, we directly use the + instance to export its OVF files. + - Converts the OVF on the temporary storage location to KVM using + **virt-v2v**. CloudStack (or the administrator) selects a running and + enabled KVM host to perform the conversion (of the previously exported OVF files) from VMware to KVM using + **virt-v2v**. If the binary is not installed, then the host will fail to convert the Instance. + In case it is installed, it will perform the conversion into + the temporary location to store the converted QCOW2 disks of the instance. + The virt-v2v conversion is a long-lasting process which can be set to + time out by the global setting ``convert.vmware.instance.to.kvm.timeout``. + The conversion process takes a long time because virt-v2v creates a + temporary instance to inspect the source VM and generate the converted + disks with the correct drivers. Additionally, it needs to copy the + converted disks into the temporary location. + - The converted instance (i.e. QCOW2 files) is then imported into the chosen KVM cluster. + Administrator can choose the KVM host to perform the import or let CloudStack choose it. Only enabled + cluster and enabled hosts are considered. + +.. note:: Please do not restart the management servers while migration is in progress as it will lead to the interruption of the process and you will need to start again. + +.. note:: As mentioned above, the migration/conversion process uses an external tool, virt-v2v, which supports most but not all the operating systems out there (this is true for both the host on which the virt-v2v tool is running as well as the guest OS of the instances being migrated by the tool). Thus, the success of the import process will, almost exclusively, depend on the success of the virt-v2v conversion. In other words, the success will vary based on factors such as the current OS version, installed packages, guest OS setup, file systems, and others. Success is not guaranteed. We strongly recommend testing the migration process before proceeding with production deployments. + +.. note:: The resulting imported VM uses the default Guest OS type: **CentOS 4.5 (32-bit)**. After importing the VM, please Edit the Instance to change the Guest OS Type accordingly. + +.. |import-vm-from-vmware-to-kvm.png| image:: /_static/images/import-vm-from-vmware-to-kvm.png + :alt: Import VMware Virtual Machines into KVM. + :width: 800 px + +.. |import-vm-from-vmware-to-kvm-options.png| image:: /_static/images/import-vm-from-vmware-to-kvm-options.png + :alt: Import VMware Virtual Machines into KVM Options. + :width: 800 px diff --git a/source/adminguide/virtual_machines/user-data.rst b/source/adminguide/virtual_machines/user-data.rst index 3fe6511649..bce96b8256 100644 --- a/source/adminguide/virtual_machines/user-data.rst +++ b/source/adminguide/virtual_machines/user-data.rst @@ -14,63 +14,191 @@ under the License. -User-Data and Meta-Data ------------------------ +User Data and Metadata +---------------------- -CloudStack provides APIs to attach up to 32KB of user-data to a deployed VM. +Users can register User Data in CloudStack and refer the registered User Data while +deploying or editing or reset User Data on an instance. The User Data content can also be +directly provided while deploying the instance. User Data content length can be up to 32kb. -There are two CloudStack APIs that can be used to store user-data: -`deployVirtualMachine `_ -and -`updateVirtualMachine `_ -They both support the parameter ``userdata=``. The value for this parameter -must be a `base64 `_-encoded multi-part MIME -message. See further below for an example of what this should look like. +Register Userdata + +To register a new User Data: + +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Compute and then User Data Library. + +#. Click Register User Data. + +#. In the dialog, make the following choices: + + - **Name**: Any desired name for the User Data. + + - **User Data**: Plain User Data content. CloudStack UI does base64 encoding. + + - **User Data parameters**: Comma separated list of variables which (if any) declared + in the User Data content. + + - **Domain**: An optional domain for the User Data. + + - **Account**: An optional account for the User Data. + +.. image:: /_static/images/register_userdata.png + :width: 400px + :align: center + :alt: Register User Data dialog box + +If User Data content has variables declared in it, user can register the User Data +with User Data parameters. + +For example, if User Data content is like below having a custom variable "variable1" + + .. code:: bash + + ## template: jinja + #cloud-config + runcmd: + - echo 'TestVariable {{ ds.meta_data.variable1 }}' >> /tmp/variable + - echo 'Hostname {{ ds.meta_data.public_hostname }}' > /tmp/hostname + +User Data has to be registered with the parameter "variable1" like below + +.. image:: /_static/images/register_userdata_with_variables.png + :width: 400px + :align: center + :alt: Register User Data with variables dialog box + +If the variables in User Data content are of a predefined metadata like "public_hostname" +or "instance_id", then User Data parameters should not declare these variables. That is +the reason in the above example "public_hostname" is not declared. + +There are three CloudStack APIs that can be used to provide User Data to instance: +deployVirtualMachine, updateVirtualMachine and resetUserDataForVirtualMachine. +These APIs accepts parameters ``userdataid`` and ``userdatadetails``. +userdatadetails is to specify the custom values for the variables which are declared +in User Data in a key value parameter map details. + +.. image:: /_static/images/deployvm_userdata.png + :width: 400px + :align: center + :alt: Provide User Data id or User Data text dialog box + +If the User Data contains variables that are declared during registration then those values +has to be specified like below, + +.. image:: /_static/images/deployvm_userdata_with_variables.png + :width: 400px + :align: center + :alt: Provide userdata id or User Data with variables text dialog box + +These details will be saved as metadata file(s) in both config drive and virtual router, +which in turn support jinja based instance metadata feature of cloud-init, +refer to https://cloudinit.readthedocs.io/en/latest/topics/instancedata.html. + +These APIs also support the parameter ``userdata=`` to provide the User Data content +directly. The value for this parameter must be a `base64 `_-encoded +multi-part MIME message. See further below for an example of what this should look like. + +The registered User Data can be linked to a Template or ISO on registration/upload/editing +using linkUserDataToTemplate API. The same API can be used to unlink the mapping of User Data and Template. + +While linking User Data to a Template/ISO User Data override policy has to be specified. +Following are the override policies available: + +Allow Override: Allow users to override User Data for the Template during instance deployment or on reset. + This is the default override policy if not specified + +Deny Override: Override of User Data isn’t allowed during instance deployment or on reset. + +Append Only: Don’t allow users to override linked User Data but allow users to pass User Data content + or ID that should be appended to the linked User Data of the Template. When the users pass User Data it is appended to the Template User Data in the form of a multipart MIME message + +This is how it looks like in Template/ISO register/upload/edit forms. + +.. image:: /_static/images/userdata_template_link.png + :width: 400px + :align: center + :alt: Linking User Data to template/ISO + +Based on these override policies, "Add Instance" UI form provides relevant options to either +override or append. If it is "Deny Override" then "Add Instance" will not allow adding user specific User Data + +Storing and accessing User Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HTTP GET parameters are limited to a length of 2048 bytes, but it is possible -to store larger user-data blobs by sending them in the body via HTTP POST +to store larger User Data blobs by sending them in the body via HTTP POST instead of GET. -From inside the VM, the user-data is accessible via the virtual router, -if the UserData service is enabled on the network offering. +From inside the instance, the User Data is accessible via the virtual router, +if the User Data service is enabled on the network offering. If you are using the DNS service of the virtual router, a special hostname -called `data-server.` is provided, that will point to a valid user-data server. +called `data-server.` is provided, that will point to a valid User Data server. Otherwise you have to determine the virtual router address via other means, such as DHCP leases. Be careful to scan all routers if you have multiple -networks attached to a VM, in case not all of them have the UserData service +networks attached to an instance, in case not all of them have the User Data service enabled. -User-data is available from the URL ``http://data-server./latest/user-data`` +User Data is available from the URL ``http://data-server./latest/user-data`` and can be fetched via curl or other HTTP client. -It is also possible to fetch VM metadata from the same service, via the URL +It is also possible to fetch instance metadata from the same service, via the URL ``http://data-server./latest/{metadata type}``. For backwards compatibility, the previous URL ``http://data-server./latest/{metadata type}`` is also supported. For metadata type, use one of the following: -- ``service-offering``. A description of the VMs service offering +- ``service-offering``. A description of the instances service offering - ``availability-zone``. The Zone name -- ``local-ipv4``. The guest IP of the VM +- ``local-ipv4``. The guest IP of the instance -- ``local-hostname``. The hostname of the VM +- ``local-hostname``. The hostname of the instance - ``public-ipv4``. The first public IP for the router. - ``public-hostname``. This is the same as public-ipv4 -- ``instance-id``. The instance name of the VM +- ``instance-id``. The instance name of the instance + +Resetting UserData +------------------ + +#. Log in to the CloudStack UI. + +#. In the left navigation bar, click Compute --> Instances. + +#. Choose the Instance to reset userdata. + + .. note:: The Instance must be in a stopped state. + +#. Click on Reset Userdata button on the Instance. + + .. note:: If the instance already has userdata applied to it, an extra dialog box will appear. + + - ``Disabled`` (Default) - This will reset the userdata using the already configured values. Skip the next step. + + - ``Enabled`` - Choose this to override the already configured values. Continue to next step. + +#. In the dialog box, choose one of the following: + - Stored Userdata: Choose another userdata entry. + + .. note:: Stored Userdata is created under Instances --> User Data + + - Manual Userdata Entry: Manually provide userdata for this Instance + +.. note:: This can also be performed via API: ``resetUserDataForVirtualMachine``: Resets the UserData for virtual machine. Determining the virtual router address without DNS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If can't or don't want to use the virtual router's DNS service, it's also -possible to determine the user-data server from a DHCP lease. +possible to determine the User Data server from a DHCP lease. #. Run the following command to find the virtual router. @@ -78,18 +206,18 @@ possible to determine the user-data server from a DHCP lease. # cat /var/lib/dhcp/dhclient.eth0.leases | grep dhcp-server-identifier | tail -1 -#. Access the data-server via its IP +#. Access the User Data server via its IP .. code:: bash # curl http://10.1.1.1/latest/user-data -Fetching user-data via the API +Fetching User Data via the API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -User-data is not included with the normal VM state for historic reasons. -To read out the base64-encoded user-data via the API, use the `getVirtualMachineUserData `_ +User Data is not included with the normal instance state for historic reasons. +To read out the base64-encoded User Data via the API, use the `getVirtualMachineUserData `_ API call: .. code:: bash @@ -101,11 +229,11 @@ Using cloud-init ~~~~~~~~~~~~~~~~ `cloud-init `_ can be used to access -and interpret user-data inside virtual machines. If you install cloud-init into your -VM templates, it will allow you to store SSH keys and user passwords on each new -VM deployment automatically (:ref:`adding-password-management-to-templates` and `using ssh keys `_). +and interpret User Data inside Instances. If you install cloud-init into your +Instance Templates, it will allow you to store SSH keys and user passwords on each new +Instance deployment automatically (:ref:`adding-password-management-to-templates` and `using ssh keys `_). -#. Install cloud-init package into a VM template: +#. Install cloud-init package into an Instance Template: .. code:: bash @@ -113,47 +241,57 @@ VM deployment automatically (:ref:`adding-password-management-to-templates` and or $ sudo apt-get install cloud-init -#. Create a datasource configuration file in the VM template: ``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg`` +#. Create a datasource configuration file in the Instance Template: ``/etc/cloud/cloud.cfg.d/99_cloudstack.cfg`` .. code:: yaml datasource_list: [ CloudStack, None ] -Custom user-data example +For more information, see `Cloud-init integration `_ + +Custom User Data example ~~~~~~~~~~~~~~~~~~~~~~~~ This example uses cloud-init to automatically update all OS packages on the first launch. -#. Create user-data, wrapped into a multi-part MIME message and encoded in base64: +#. Register the following User Data in CloudStack. If APIs are used to register User Data or to + provide direct User Data text then User Data needs to be wrapped into a multi-part MIME message + and encoded in base64: -.. code:: bash + .. code:: bash - base64 < +.. note:: When using multipart User Data, cloud-init expects User Data format of one particular type only in one multipart section. Disclaimer ~~~~~~~~~~ diff --git a/source/adminguide/virtual_machines/virtual_appliances.rst b/source/adminguide/virtual_machines/virtual_appliances.rst index 5d9ad262fb..d5f167fd8c 100644 --- a/source/adminguide/virtual_machines/virtual_appliances.rst +++ b/source/adminguide/virtual_machines/virtual_appliances.rst @@ -17,20 +17,20 @@ About Virtual Appliances ------------------------ CloudStack allows users to deploy virtual appliances on VMware such as its been made directly though vCenter. -Vendors of virtual appliances for VMware often produce ‘templates’ of their appliances in an OVA format. +Vendors of virtual appliances for VMware often produce ‘Templates’ of their appliances in an OVA format. An OVA file contain disc images, as well as the configuration data of the virtual appliance and also at times a EULA which must be acknowledged. Virtual Appliances are supported only on VMware. .. note:: - Since version 4.15.1, administrators and users can register virtual appliance templates by selecting the option 'Read VM Settings from OVA' on the template registration. + Since version 4.15.1, administrators and users can register virtual appliance Templates by selecting the option 'Read instance Settings from OVA' on the Template registration. Deployment options (configurations) ----------------------------------- -VMware templates can provide different deployment options in their OVF descriptor file. CloudStack obtains -the different deployment options when the template is registered and it displays them to the users -in the virtual machine deployment wizard, under the 'Compute Offering' section. +VMware Templates can provide different deployment options in their OVF descriptor file. CloudStack obtains +the different deployment options when the Template is registered and it displays them to the users +in the Instance deployment wizard, under the 'Compute Offering' section. After the user selects a deployment option, CloudStack lists the compute offerings which match or exceed the deployment options hardware requirements for CPU and memory. @@ -51,7 +51,7 @@ The 'Compute Offering' section will be similar to this: Network interfaces ------------------ -In case the template requires the virtual appliance to connect different network interfaces, these are displayed in the 'Networks' section, similar to this: +In case the Template requires the virtual appliance to connect different network interfaces, these are displayed in the 'Networks' section, similar to this: |vapps-networks.png| @@ -59,7 +59,7 @@ In case the template requires the virtual appliance to connect different network Properties ---------- -If the template contains properties that require the user input, those are being displayed on the 'Properties' section, similar to this: +If the Template contains properties that require the user input, those are being displayed on the 'Properties' section, similar to this: |vapps-properties.png| @@ -67,7 +67,7 @@ If the template contains properties that require the user input, those are being End-user license agreements --------------------------- -If the template contains one or more end-user license agreements, the user must accept them prior to deploy their virtual appliance. +If the Template contains one or more end-user license agreements, the user must accept them prior to deploy their virtual appliance. If the license agreements are not accepted, then it is not possible to deploy a virtual appliance. |vapps-eulas.png| @@ -75,4 +75,4 @@ If the license agreements are not accepted, then it is not possible to deploy a Advanced deployment settings ---------------------------- -It is not possible to choose the boot type (BIOS, UEFI) and boot mode for virtual appliances. The boot mode and type used by the virtual appliances is defined in the template. \ No newline at end of file +It is not possible to choose the boot type (BIOS, UEFI) and boot mode for virtual appliances. The boot mode and type used by the virtual appliances is defined in the Template. \ No newline at end of file diff --git a/source/adminguide/vm_volume_allocators.rst b/source/adminguide/vm_volume_allocators.rst new file mode 100644 index 0000000000..c15ebd8796 --- /dev/null +++ b/source/adminguide/vm_volume_allocators.rst @@ -0,0 +1,139 @@ +.. 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. + + +VM and Volume Allocators +====================== + +Each Instance must be deployed in suitable deployment destination. Deployment destination is set of recommended resources that you can choose for deploying an instance. +A deployment planner provides the suitable deployment destination that is required for a instance. + +Allocators are used to figure out suitable host and storage pools for deploying the Instance: + +#. VM Allocator +#. Volume Allocator + + +VM Allocator +------------ + +VM allocator returns suitable hosts in the cluster where you can deploy the given instance. Various parameters e.g. CPU and +RAM capacity, current state of the host are considered to decide the host. + +VM allocator supports following algorithms to select a host in the cluster: + +.. cssclass:: table-striped table-bordered table-hover + +============================= ======================== +Algorithm Description +============================= ======================== +random Selects a host in the cluster randomly. +firstfit Selects the first available host in the cluster. +userdispersing Selects the host running least instances for the account, aims to spread out the instances belonging to a single user account. +userconcentratedpod_random Selects the host randomly aiming to keep all instances belonging to single user account in same pod. +userconcentratedpod_firstfit Selects the first suitable host from a pod running most instances for the user. +firstfitleastconsumed Selects the first host after sorting eligible hosts by least allocated resources (such as CPU or RAM). +============================= ======================== + +Use global configuration parameter: +**vm.allocation.algorithm** to specify the algorithm that the Allocator must use. By default it is configured to use "random" algorithm. + + +Volume Allocator +-------------- + +Volume allocator returns suitable storage pools available in the cluster where volumes of the given instance can be created. +To decide the storage pools, it considers factors such as disk offering, storage capacity, availability scope etc. + +Volume allocator supports following algorithms to select a host in the cluster: + +.. cssclass:: table-striped table-bordered table-hover + +============================= ======================== +Algorithm Description +============================= ======================== +random Selects a storage pool in the cluster randomly. +firstfit Selects the first available storage pool in the cluster. +userdispersing Selects the storage pool running least instances for the account, aims to spread out the instances belonging to a single user account. +userconcentratedpod_random Selects the storage pool randomly aiming to keep all instances belonging to single user account in same pod. +userconcentratedpod_firstfit Selects the first suitable pool from a pod running most instances for the user. +firstfitleastconsumed Selects the first storage pool after sorting eligible pools by least allocated resources. +============================= ======================== + +.. note:: + Since 4.21.0, dedicated named configuration is provided for admin to configure volume allocation algorithm. + + **volume.allocation.algorithm**: random (default) + + Before 4.21.0, **vm.allocation.algorithm** was used for both VM as well as Volume allocation. + + +Cluster, Pod and Host Ordering +============================== + +Overview +-------- + +`The host.capacityType.to.order.clusters` is a global advanced configuration parameter in Apache CloudStack that controls how pods, clusters, +and hosts are prioritized during Instance deployment, based on available CPU, RAM, or a weighted combination of both in Host. +This configuration is specifically leveraged when the VM allocation algorithm is set to `firstfitleastconsumed`. + +Configuration +------------- + +Key: `host.capacityType.to.order.clusters` + +.. cssclass:: table-striped table-bordered table-hover + +========= ======================== +Value Behavior +========= ======================== +CPU Prioritizes resources with the most available CPU. +RAM Prioritizes resources with the most available memory. +COMBINED Uses a weighted formula to balance CPU and RAM in prioritization. +========= ======================== + +**Additional Configuration for COMBINED** + +- Key: `host.capacityType.to.order.clusters.cputomemoryweight` +- Type: Float(0.0 to 1.0) +- Default: 0.5 +- Purpose: Determines the weight of CPU vs RAM in the combined capacity calculation. + +Capacity calculation formula: + +.. code:: bash + + capacity = (host.capacityType.to.order.clusters.cputomemoryweight * CPU) + ((1 - host.capacityType.to.order.clusters.cputomemoryweight) * RAM) + + +This allows flexible tuning of prioritization depending on workload sensitivity. + +Example Configuration +--------------------- + +.. code:: bash + + host.capacityType.to.order.clusters: COMBINED + host.capacityType.to.order.clusters.cputomemoryweight: 0.7 + +Above config prioritizes CPU at 70% weight and RAM at 30% when ranking pods, clusters, and hosts. + +.. note:: + - `host.capacityType.to.order.clusters` is only respected for host ordering when: + .. code:: bash + + vm.allocation.algorithm: firstfitleastconsumed + - When using COMBINED, make sure to tune cpu.to.memory.capacity.weight to reflect your environment’s resource constraints and workload profiles. diff --git a/source/conceptsandterminology/choosing_deployment_architecture.rst b/source/conceptsandterminology/choosing_deployment_architecture.rst index 3dcbac5594..55f673a05f 100644 --- a/source/conceptsandterminology/choosing_deployment_architecture.rst +++ b/source/conceptsandterminology/choosing_deployment_architecture.rst @@ -27,20 +27,20 @@ Small-Scale Deployment |Small-Scale Deployment| -This diagram illustrates the network architecture of a small-scale +This diagram illustrates the Network architecture of a small-scale CloudStack deployment. - A firewall provides a connection to the Internet. The firewall is configured in NAT mode. The firewall forwards HTTP requests and API calls from the Internet to the Management Server. The Management - Server resides on the management network. + Server resides on the Management Network. - A layer-2 switch connects all physical servers and storage. - A single NFS server functions as both the primary and secondary storage. -- The Management Server is connected to the management network. +- The Management Server is connected to the Management Network. Large-Scale Redundant Setup @@ -48,7 +48,7 @@ Large-Scale Redundant Setup |Large-Scale Redundant Setup| -This diagram illustrates the network architecture of a large-scale +This diagram illustrates the Network architecture of a large-scale CloudStack deployment. - A layer-3 switching layer is at the core of the data center. A router @@ -59,8 +59,8 @@ CloudStack deployment. mode. The firewalls provide the following functions: - Forwards HTTP requests and API calls from the Internet to the - Management Server. The Management Server resides on the management - network. + Management Server. The Management Server resides on the Management + Network. - When the cloud spans multiple zones, the firewalls should enable site-to-site VPN such that servers in different zones can directly @@ -72,9 +72,9 @@ CloudStack deployment. - The Management Server cluster (including front-end load balancers, Management Server nodes, and the MySQL database) is connected to the - management network through a pair of load balancers. + Management Network through a pair of load balancers. -- Secondary storage servers are connected to the management network. +- Secondary storage servers are connected to the Management Network. - Each pod contains storage and computing servers. Each storage and computing server should have redundant NICs connected to separate @@ -85,10 +85,10 @@ Separate Storage Network ------------------------ In the large-scale redundant setup described in the previous section, -storage traffic can overload the management network. A separate storage -network is optional for deployments. Storage protocols such as iSCSI are -sensitive to network delays. A separate storage network ensures guest -network traffic contention does not impact storage performance. +storage traffic can overload the Management Network. A separate Storage +Network is optional for deployments. Storage protocols such as iSCSI are +sensitive to network delays. A separate Storage Network ensures Guest +Network traffic contention does not impact storage performance. Multi-Node Management Server @@ -127,19 +127,19 @@ Management Server installation in Data Center 2. |Separate Storage Network| -This diagram illustrates a setup with a separate storage network. Each +This diagram illustrates a setup with a separate Storage Network. Each server has four NICs, two connected to pod-level network switches and -two connected to storage network switches. +two connected to Storage Network switches. -There are two ways to configure the storage network: +There are two ways to configure the Storage Network: - Bonded NIC and redundant switches can be deployed for NFS. In NFS deployments, redundant switches and bonded NICs still result in one - network (one CIDR block+ default gateway address). + Network (one CIDR block+ default gateway address). -- iSCSI can take advantage of two separate storage networks (two CIDR +- iSCSI can take advantage of two separate Storage Networks (two CIDR blocks each with its own default gateway). Multipath iSCSI client can - failover and load balance between separate storage networks. + failover and load balance between separate Storage Networks. |NIC Bonding And Multipath I/O| @@ -165,38 +165,38 @@ supported by CloudStack. The following table provides this information. .. cssclass:: table-striped table-bordered table-hover -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Feature | XenServer | vSphere | KVM - | LXC | HyperV | Bare | -| | | | RHEL | | | Metal | -+===================================+===========+==========+========+=====+========+=======+ -| Network Throttling | Yes | Yes | Yes | No | ? | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Security groups in zones that use | Yes | No | Yes | Yes | ? | No | -| basic networking | | | | | | | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| iSCSI | Yes | Yes | Yes | Yes | Yes | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| FibreChannel | Yes | Yes | Yes | Yes | Yes | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Local Disk | Yes | Yes | Yes | Yes | Yes | Yes | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| HA | Yes | Yes | Yes | ? | Yes | N/A | -| | | (Native) | | | | | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Snapshots of local disk | Yes | Yes | Yes | ? | ? | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Local disk as data disk | Yes | No | Yes | Yes | Yes | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Work load balancing | No | DRS | No | No | ? | N/A | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Manual live migration of VMs from | Yes | Yes | Yes | ? | Yes | N/A | -| host to host | | | | | | | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ -| Conserve management traffic IP | Yes | No | Yes | Yes | ? | N/A | -| address by using link local | | | | | | | -| network to communicate with | | | | | | | -| virtual router | | | | | | | -+-----------------------------------+-----------+----------+--------+-----+--------+-------+ ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Feature | XenServer | vSphere | KVM - | LXC | HyperV | Bare | +| | | | RHEL | | | Metal | ++=========================================+===========+==========+========+=====+========+=======+ +| Network Throttling | Yes | Yes | Yes | No | ? | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Security groups in zones that use | Yes | No | Yes | Yes | ? | No | +| basic networking | | | | | | | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| iSCSI | Yes | Yes | Yes | Yes | Yes | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| FibreChannel | Yes | Yes | Yes | Yes | Yes | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Local Disk | Yes | Yes | Yes | Yes | Yes | Yes | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| HA | Yes | Yes | Yes | ? | Yes | N/A | +| | | (Native) | | | | | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Snapshots of local disk | Yes | Yes | Yes | ? | ? | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Local disk as data disk | Yes | No | Yes | Yes | Yes | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Work load balancing | No | DRS | No | No | ? | N/A | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Manual live migration of Instances from | Yes | Yes | Yes | ? | Yes | N/A | +| host to host | | | | | | | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ +| Conserve management traffic IP | Yes | No | Yes | Yes | ? | N/A | +| address by using link local | | | | | | | +| network to communicate with | | | | | | | +| virtual router | | | | | | | ++-----------------------------------------+-----------+----------+--------+-----+--------+-------+ Hypervisor Support for Primary Storage @@ -228,7 +228,7 @@ hypervisors. | SMB/CIFS | No | No | No | No | Yes | +----------------------------------+-------------+---------------+----------------+----------------+--------+ -XenServer uses a clustered LVM system to store VM images on iSCSI and +XenServer uses a clustered LVM system to store Instance images on iSCSI and Fiber Channel volumes and does not support over-provisioning in the hypervisor. The storage server itself, however, can support thin-provisioning. As a result the CloudStack can still support storage @@ -311,7 +311,7 @@ Setup Best Practices reliability. - 10G networks are generally recommended for storage access when larger - servers that can support relatively more VMs are used. + servers that can support relatively more Instances are used. - Host capacity should generally be modeled in terms of RAM for the guests. Storage and CPU may be overprovisioned. RAM may not. RAM is @@ -319,7 +319,7 @@ Setup Best Practices - (XenServer) Configure the XenServer dom0 settings to allocate more memory to dom0. This can enable XenServer to handle larger numbers of - virtual machines. We recommend 2940 MB of RAM for XenServer dom0. For + Instances. We recommend 2940 MB of RAM for XenServer dom0. For instructions on how to do this, see `http://support.citrix.com/article/CTX126531 `_. @@ -333,24 +333,24 @@ Maintenance Best Practices - Monitor host disk space. Many host failures occur because the host's root disk fills up from logs that were not rotated adequately. -- Monitor the total number of VM instances in each cluster, and disable +- Monitor the total number of 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 redeployed. + increase the Instance load on the other hosts as the Instances are redeployed. Consult the documentation for your chosen hypervisor to find the - maximum permitted number of VMs per host, then use CloudStack global + maximum permitted number of Instances per host, then use CloudStack global configuration settings to set this as the default limit. Monitor the - VM activity in each cluster and keep the total number of VMs below a + Instance activity in each cluster and keep the total number of Instances 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 + Instances you can permit in the cluster is at most (N-1) \* + (per-host-limit). Once a cluster reaches this number of Instances, use the CloudStack UI to disable allocation to the cluster. .. warning:: - The lack of up-do-date hotfixes can lead to data corruption and lost VMs. + The lack of up-do-date hotfixes can lead to data corruption and lost Instances. Be sure all the hotfixes provided by the hypervisor vendor are applied. Track the release of hypervisor patches through your hypervisor vendor’s support diff --git a/source/conceptsandterminology/concepts.rst b/source/conceptsandterminology/concepts.rst index d938b918ae..f621ffaa6d 100644 --- a/source/conceptsandterminology/concepts.rst +++ b/source/conceptsandterminology/concepts.rst @@ -11,20 +11,20 @@ "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. + under the License What is Apache CloudStack? -------------------------- -Apache CloudStack is an open source Infrastructure-as-a-Service platform that -manages and orchestrates pools of storage, network, and computer resources to -build a public or private IaaS compute cloud. +Apache CloudStack is an open source Infrastructure-as-a-Service platform that +manages and orchestrates pools of storage, network, and computer resources to +build a public or private IaaS compute cloud. With CloudStack you can: -- Set up an on-demand elastic cloud computing service. +- Set up an on-demand elastic cloud computing service. - Allow end-users to provision resources @@ -35,9 +35,9 @@ What can Apache CloudStack do? Multiple Hypervisor Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack works with a variety of hypervisors and hypervisor-like -technologies. A single cloud can contain multiple hypervisor implementations. -As of the current release CloudStack supports: +CloudStack works with a variety of hypervisors and hypervisor-like +technologies. A single cloud can contain multiple hypervisor implementations. +As of the current release CloudStack supports: - BareMetal (via IPMI) @@ -57,105 +57,104 @@ As of the current release CloudStack supports: Massively Scalable Infrastructure Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack can manage tens of thousands of physical servers installed in -geographically distributed datacenters. The management server scales -near-linearly eliminating the need for cluster-level management servers. -Maintenance or other outages of the management server can occur without -affecting the virtual machines running in the cloud. +CloudStack can manage tens of thousands of physical servers installed in +geographically distributed datacenters. The management server scales +near-linearly eliminating the need for cluster-level management servers. +Maintenance or other outages of the management server can occur without +affecting the Instances running in the cloud. Automatic Cloud Configuration Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack automatically configures the network and storage settings for each -virtual machine deployment. Internally, a pool of virtual appliances support -the operation of configuration of the cloud itself. These appliances offer -services such as firewalling, routing, DHCP, VPN, console proxy, storage -access, and storage replication. The extensive use of horizontally scalable -virtual machines simplifies the installation and ongoing operation of a cloud. +CloudStack automatically configures the network and storage settings for each +Instance deployment. Internally, a pool of virtual appliances support +the operation of configuration of the cloud itself. These appliances offer +services such as firewalling, routing, DHCP, VPN, console proxy, storage +access, and storage replication. The extensive use of horizontally scalable +Instances simplifies the installation and ongoing operation of a cloud. Graphical User Interface ~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack offers an administrators web interface used for provisioning and -managing the cloud, as well as an end-user's Web interface, used for running -VMs and managing VM templates. The UI can be customized to reflect the desired +CloudStack offers an administrators web interface used for provisioning and +managing the cloud, as well as an end-user's Web interface, used for running +Instances and managing Instance Templates. The UI can be customized to reflect the desired service provider or enterprise look and feel. API ~~~ -CloudStack provides a REST-like API for the operation, management and use of -the cloud. +CloudStack provides a REST-like API for the operation, management and use of +the cloud. AWS EC2 API Support ~~~~~~~~~~~~~~~~~~~ -CloudStack provides an EC2 API translation layer to permit the common EC2 -tools to be used in the use of a CloudStack cloud. +CloudStack provides an EC2 API translation layer to permit the common EC2 +tools to be used in the use of a CloudStack cloud. High Availability ~~~~~~~~~~~~~~~~~ -CloudStack has a number of features to increase the availability of the -system. The Management Server itself may be deployed in a multi-node -installation where the servers are load balanced. MySQL may be configured to -use replication to provide for failover in the event of database loss. For the -hosts, CloudStack supports NIC bonding and the use of separate networks for +CloudStack has a number of features to increase the availability of the +system. The Management Server itself may be deployed in a multi-node +installation where the servers are load balanced. MySQL may be configured to +use replication to provide for failover in the event of database loss. For the +hosts, CloudStack supports NIC bonding and the use of separate networks for storage as well as iSCSI Multipath. Deployment Architecture Overview -------------------------------- -Generally speaking, most CloudStack deployments consist of the management -server and the resources to be managed. During deployment you inform the -management server of the resources to be managed, such as IP address blocks, -storage devices, hypervisors, and VLANs. +Generally speaking, most CloudStack deployments consist of the management +server and the resources to be managed. During deployment you inform the +management server of the resources to be managed, such as IP address blocks, +storage devices, hypervisors, and VLANs. -The minimum installation consists of one machine running the CloudStack -Management Server and another machine to act as the cloud infrastructure (in -this case, a very simple infrastructure consisting of one host running -hypervisor software). In its smallest deployment, a single machine can act as +The minimum installation consists of one machine running the CloudStack +Management Server and another machine to act as the cloud infrastructure (in +this case, a very simple infrastructure consisting of one host running +hypervisor software). In its smallest deployment, a single machine can act as both the Management Server and the hypervisor host (using the KVM hypervisor). .. image:: /_static/images/basic-deployment.png -A more full-featured installation consists of a highly-available multi-node -Management Server installation and up to tens of thousands of hosts using any +A more full-featured installation consists of a highly-available multi-node +Management Server installation and up to tens of thousands of hosts using any of several networking technologies. Management Server Overview ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The management server orchestrates and allocates the resources in your cloud +The management server orchestrates and allocates the resources in your cloud deployment. -The management server typically runs on a dedicated machine or as a virtual -machine. It controls allocation of virtual machines to hosts and assigns -storage and IP addresses to the virtual machine instances. The Management -Server runs in an Apache Tomcat container and requires a MySQL database for -persistence. +The management server typically runs on a dedicated machine or as a virtual +machine. It controls allocation of Instances to hosts and assigns +storage and IP addresses to the Instances. The Management Server runs +in an Apache Tomcat container and requires a MySQL database for persistence. The management server: -- Provides the web interface for both the adminstrator and end user. +- Provides the web interface for both the administrator and end user. -- Provides the API interfaces for both the CloudStack API as well as the EC2 - interface. +- Provides the API interfaces for both the CloudStack API as well as the EC2 + interface. -- Manages the assignment of guest VMs to a specific compute resource +- Manages the assignment of guest Instances to a specific compute resource -- Manages the assignment of public and private IP addresses. +- Manages the assignment of public and private IP addresses. -- Allocates storage during the VM instantiation process. +- Allocates storage during the VM instantiation process. -- Manages snapshots, disk images (templates), and ISO images. +- Manages Snapshots, disk images (Templates), and ISO images. - Provides a single point of configuration for your cloud. @@ -164,41 +163,41 @@ The management server: Cloud Infrastructure Overview ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Resources within the cloud are managed as follows: +Resources within the cloud are managed as follows: -- Regions: A collection of one or more geographically proximate zones managed - by one or more management servers. +- Regions: A collection of one or more geographically proximate zones managed + by one or more management servers. -- Zones: Typically, a zone is equivalent to a single datacenter. A zone +- Zones: Typically, a zone is equivalent to a single datacenter. A zone consists of one or more pods and secondary storage. -- Pods: A pod is usually a rack, or row of racks that includes a layer-2 +- Pods: A pod is usually a rack, or row of racks that includes a layer-2 switch and one or more clusters. -- Clusters: A cluster consists of one or more homogenous hosts and primary - storage. +- Clusters: A cluster consists of one or more homogeneous hosts and primary + storage. -- Host: A single compute node within a cluster; often a hypervisor. +- Host: A single compute node within a cluster; often a hypervisor. -- Primary Storage: A storage resource typically provided to a single cluster - for the actual running of instance disk images. (Zone-wide primary storage +- Primary Storage: A storage resource typically provided to a single cluster + for the actual running of Instance disk images. (Zone-wide primary storage is an option, though not typically used.) -- Secondary Storage: A zone-wide resource which stores disk templates, ISO - images, and snapshots. +- Secondary Storage: A zone-wide resource which stores disk Templates, ISO + images, and Snapshots. Networking Overview ~~~~~~~~~~~~~~~~~~~ -CloudStack offers many types of networking, but they typically fall into one -of two scenarios: +CloudStack offers many types of networking, but they typically fall into one +of two scenarios: -- Basic: Most analogous to AWS-classic style networking. Provides a single - flat layer-2 network where guest isolation is provided at layer-3 by the - hypervisors bridge device. +- Basic: Most analogous to AWS-classic style networking. Provides a single + flat layer-2 network where guest isolation is provided at layer-3 by the + hypervisors bridge device. -- Advanced: This typically uses layer-2 isolation such as VLANs, though this +- Advanced: This typically uses layer-2 isolation such as VLANs, though this category also includes SDN technologies such as Nicira NVP. @@ -221,9 +220,9 @@ technique for providing fault tolerance and disaster recovery. By grouping zones into regions, the cloud can achieve higher availability and scalability. User accounts can span regions, so that -users can deploy VMs in multiple, widely-dispersed regions. Even if one +users can deploy Instances in multiple, widely-dispersed regions. Even if one of the regions becomes unavailable, the services are still available to -the end-user through VMs deployed in another region. And by grouping +the end-user through Instances deployed in another region. And by grouping communities of zones under their own nearby Management Servers, the latency of communications within the cloud is reduced compared to managing widely-dispersed zones from a single central Management Server. @@ -234,11 +233,11 @@ creating reports or invoices for each geographic region. .. figure:: /_static/images/region-overview.png -Regions are visible to the end user. When a user starts a guest VM on a +Regions are visible to the end user. When a user starts a Guest Instance on a particular CloudStack Management Server, the user is implicitly selecting that region for their guest. Users might also be required to -copy their private templates to additional regions to enable creation of -guest VMs using their templates in those regions. +copy their private Templates to additional regions to enable creation of +Guest Instances using their Templates in those regions. .. _about-zones: @@ -266,10 +265,10 @@ A zone consists of: .. figure:: /_static/images/zone-overview.png -Zones are visible to the end user. When a user starts a guest VM, the +Zones are visible to the end user. When a user starts a Guest Instance, the user must select a zone for their guest. Users might also be required to -copy their private templates to additional zones to enable creation of -guest VMs using their templates in those zones. +copy their private Templates to additional zones to enable creation of +Guest Instances using their Templates in those zones. Zones can be public or private. Public zones are visible to all users. This means that any user may create a guest in that zone. Private zones @@ -310,11 +309,11 @@ the zone. If you are provisioning multiple VMware Datacenters, each one will be set up as a single zone in CloudStack. .. note:: - If you are upgrading from a previous CloudStack version, and your existing - deployment contains a zone with clusters from multiple VMware Datacenters, - that zone will not be forcibly migrated to the new model. It will continue - to function as before. However, any new zone-wide operations, such as - zone-wide primary storage and live storage migration, will not be available + If you are upgrading from a previous CloudStack version, and your existing + deployment contains a zone with clusters from multiple VMware Datacenters, + that zone will not be forcibly migrated to the new model. It will continue + to function as before. However, any new zone-wide operations, such as + zone-wide primary storage and live storage migration, will not be available in that zone. .. _about-pods: @@ -337,12 +336,12 @@ About Clusters ~~~~~~~~~~~~~~ A cluster provides a way to group hosts. To be precise, a cluster is a -XenServer server pool, a set of KVM servers, , or a VMware cluster +XenServer server pool, a set of KVM servers or a VMware cluster preconfigured in vCenter. The hosts in a cluster all have identical hardware, run the same hypervisor, are on the same subnet, and access -the same shared primary storage. Virtual machine instances (VMs) can be -live-migrated from one host to another within the same cluster, without -interrupting service to the user. +the same shared primary storage. Instances can be live-migrated from +one host to another within the same cluster, without interrupting service +to the user. A cluster is the fourth-largest organizational unit within a CloudStack deployment. Clusters are contained within pods, and pods are contained @@ -371,8 +370,8 @@ About Hosts ~~~~~~~~~~~ A host is a single computer. Hosts provide the computing resources that -run guest virtual machines. Each host has hypervisor software installed -on it to manage the guest VMs. For example, a host can be a Citrix +run Guest Instances. Each host has hypervisor software installed +on it to manage the Guest Instances. For example, a host can be a Citrix XenServer server, a Linux KVM-enabled server, an ESXi server, or a Windows Hyper-V server. @@ -384,7 +383,7 @@ within regions. Hosts in a CloudStack deployment: - Provide the CPU, memory, storage, and networking resources needed to - host the virtual machines + host the Instances - Interconnect using a high bandwidth TCP/IP network and connect to the Internet @@ -397,7 +396,7 @@ Hosts in a CloudStack deployment: be homogeneous Additional hosts can be added at any time to provide more capacity for -guest VMs. +Guest Instances. CloudStack automatically detects the amount of CPU and memory resources provided by the hosts. @@ -418,7 +417,7 @@ About Primary Storage ~~~~~~~~~~~~~~~~~~~~~ Primary storage is associated with a cluster, and it stores -virtual disks for all the VMs running on hosts in that cluster. +virtual disks for all the Instances running on hosts in that cluster. On KVM and VMware, you can provision primary storage on a per-zone basis. You can add multiple primary storage servers to a cluster or zone. At @@ -428,8 +427,8 @@ virtual disks to particular primary storage devices. It is useful to set up zone-wide primary storage when you want to avoid extra data copy operations. With cluster-based primary storage, data in -the primary storage is directly available only to VMs within that -cluster. If a VM in a different cluster needs some of the data, it must +the primary storage is directly available only to Instances within that +cluster. If an Instance in a different cluster needs some of the data, it must be copied from one cluster to another, using the zone's secondary storage as an intermediate step. This operation can be unnecessarily time-consuming. @@ -457,23 +456,46 @@ for example: - Dell EMC PowerFlex™ (v3.5) +- HPE Primera/3PAR for FiberChannel + +- Pure FlashArray for FiberChannel + If you intend to use only local disk for your installation, you can skip adding separate primary storage. +Changing the Scope of the Primary Storage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Starting 4.19.1.0, it is possible to change the Scope of a Primary Storage +from Zone-wide to Cluster-wide and vice versa. The option will be visible only +after the Primary Storage has been disabled. + +This feature is tested and supported for the following hypervisor and storage +combinations: + +- KVM with NFS + +- KVM with CEPH/RBD + +- VMWare with NFS + +It is possible to use this functionality with other configurations but some +manual intervention might be needed by the Administrator to make it work. + About Secondary Storage ~~~~~~~~~~~~~~~~~~~~~~~ Secondary storage stores the following: -- Templates — OS images that can be used to boot VMs and can include +- Templates — OS images that can be used to boot Instances and can include additional configuration information, such as installed applications - ISO images — disc images containing data or bootable media for operating systems -- Disk volume snapshots — saved copies of VM data which can be used for - data recovery or to create new templates +- Disk Volume Snapshots — saved copies of Instance data which can be used for + data recovery or to create new Templates The items in secondary storage are available to all hosts in the scope of the secondary storage, which may be defined as per zone or per @@ -481,8 +503,8 @@ region. To make items in secondary storage available to all hosts throughout the cloud, you can add object storage in addition to the zone-based NFS -Secondary Staging Store. It is not necessary to copy templates and -snapshots from one zone to another, as would be required when using zone +Secondary Staging Store. It is not necessary to copy Templates and +Snapshots from one zone to another, as would be required when using zone NFS alone. Everything is available everywhere. For Hyper-V hosts, SMB/CIFS storage is supported. @@ -493,16 +515,35 @@ Simple Storage Service (S3) object storage. When using one of these storage plugins, you configure Swift or S3 storage for the entire CloudStack, then set up the NFS Secondary Staging Store for each zone. The NFS storage in each zone acts as a staging area through which all -templates and other secondary storage data pass before being forwarded +Templates and other secondary storage data pass before being forwarded to Swift or S3. The backing object storage acts as a cloud-wide -resource, making templates and other data available to any zone in the +resource, making Templates and other data available to any zone in the cloud. .. warning:: - Heterogeneous Secondary Storage is not supported in Regions. For example, - you cannot set up multiple zones, one using NFS secondary and the other + Heterogeneous Secondary Storage is not supported in Regions. For example, + you cannot set up multiple zones, one using NFS secondary and the other using S3 or Swift secondary. +.. _about-object-storage: + +About Object Storage +~~~~~~~~~~~~~~~~~~~~~~~ +Object storage (also known as object-based storage) is a data storage that manages data as objects. +CloudStack admin can setup supported Object Storage systems and add them to CloudStack as an Object Storage Pool. +Users can create buckets within the object storage pool. +The basic storage units of Object Store are objects. Any type of data, regardless of content type, is stored as an object. +Buckets are logical containers for storing objects. + +About Shared FileSystems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +CloudStack users can setup CloudStack managed Shared FileSystems which can be mounted via NFS. +Users can choose the service offering, disk offering, filesystem format and network. +The Shared FileSystem is deployed on an Instance with the specified service offering. +A data volume is created using the given disk offering and attached to the Instance. +User can specify which filesystem to use (XFS, EXT4). +The filesystem is created on the data volume and exported via NFS. +All Instances in the guest network can mount and read/write to the Shared FileSystem. About Physical Networks ~~~~~~~~~~~~~~~~~~~~~~~ @@ -538,8 +579,8 @@ Basic Zone Network Traffic Types When basic networking is used, there can be only one physical network in the zone. That physical network carries the following traffic types: -- Guest. When end users run VMs, they generate guest traffic. The guest - VMs communicate with each other over a network that can be referred +- Guest. When end users run Instances, they generate guest traffic. The guest + Instances communicate with each other over a network that can be referred to as the guest network. Each pod in a basic zone is a broadcast domain, and therefore each pod has a different IP range for the guest network. The administrator must configure the IP range for each pod. @@ -555,25 +596,23 @@ the zone. That physical network carries the following traffic types: We strongly recommend the use of separate NICs for management traffic and guest traffic. -- Public. Public traffic is generated when VMs in the cloud access the - Internet. Publicly accessible IPs must be allocated for this purpose. - End users can use the CloudStack UI to acquire these IPs to implement - NAT between their guest network and the public network, as described - in Acquiring a New IP Address. +- Public. Public traffic doesn't exist in the Basic Zone. Instead, the Guest + network can be assigned publicly routable IP space in case you want your + Instances to be directly exposed to the Internet -- Storage. While labeled "storage" this is specifically about secondary - storage, and doesn't affect traffic for primary storage. This - includes traffic such as VM templates and snapshots, which is sent +- Storage. While labeled "storage" this is specifically about Secondary + Storage traffic, and doesn't affect traffic for primary storage. This + includes traffic such as Instance Templates and Snapshots, which is sent between the secondary storage VM and secondary storage servers. CloudStack uses a separate Network Interface Controller (NIC) named - storage NIC for storage network traffic. Use of a storage NIC that - always operates on a high bandwidth network allows fast template and - snapshot copying. You must configure the IP range to use for the - storage network. + storage NIC for Storage Network traffic. Use of a storage NIC that + always operates on a high bandwidth network allows fast Template and + Snapshot copying. You must configure the IP range to use for the + Storage Network. In a basic network, configuring the physical network is fairly straightforward. In most cases, you only need to configure one guest -network to carry traffic that is generated by guest VMs. If you use a +network to carry traffic that is generated by Guest Instances. If you use a NetScaler load balancer and enable its elastic IP and elastic load balancing (EIP and ELB) features, you must also configure a network to carry public traffic. CloudStack takes care of presenting the necessary @@ -599,13 +638,13 @@ traffic types, and you need to let CloudStack know which type of network traffic you want each network to carry. The traffic types in an advanced zone are: -- Guest. When end users run VMs, they generate guest traffic. The guest - VMs communicate with each other over a network that can be referred +- Guest. When end users run Instances, they generate guest traffic. The guest + Instances communicate with each other over a network that can be referred to as the guest network. This network can be isolated or shared. In an isolated guest network, the administrator needs to reserve VLAN ranges to provide isolation for each CloudStack account’s network (potentially a large number of VLANs). In a shared guest network, all - guest VMs share a single network. + Guest Instances share a single network. - Management. When CloudStack’s internal resources communicate with each other, they generate management traffic. This includes @@ -614,21 +653,30 @@ zone are: communicates directly with the CloudStack Management Server. You must configure the IP range for the system VMs to use. -- Public. Public traffic is generated when VMs in the cloud access the - Internet. Publicly accessible IPs must be allocated for this purpose. +- Public. Public traffic is generated when Instances in the cloud need to access + systems that are external to CloudStack. Guest Instances will route the + traffic through their Virtual Router to access external systems. End users can use the CloudStack UI to acquire these IPs to implement - NAT between their guest network and the public network, as described + NAT between their guest network and the Public Network, as described in “Acquiring a New IP Address” in the Administration Guide. + Public IPs are assigned to the "Public" interface of system VMs, including + Virtual Routers. + +.. note:: + The IP space used in a "Public" network can either be really publicly + routable IP space (e.g. in case of a Public cloud setup), or can be + any other company internal (RFC 1918) IP space that is not used with other + CloudStack networks (e.g. in case of a Private cloud setup - Storage. While labeled "storage" this is specifically about secondary storage, and doesn't affect traffic for primary storage. This - includes traffic such as VM templates and snapshots, which is sent + includes traffic such as Instance Templates and Snapshots, which is sent between the secondary storage VM and secondary storage servers. CloudStack uses a separate Network Interface Controller (NIC) named - storage NIC for storage network traffic. Use of a storage NIC that - always operates on a high bandwidth network allows fast template and - snapshot copying. You must configure the IP range to use for the - storage network. + storage NIC for Storage Network traffic. Use of a storage NIC that + always operates on a high bandwidth network allows fast Template and + Snapshot copying. You must configure the IP range to use for the + Storage Network. These traffic types can each be on a separate physical network, or they can be combined with certain restrictions. When you use the Add Zone @@ -646,14 +694,14 @@ account, in which case only the named account may create guests that attach to these networks. The networks are defined by a VLAN ID, IP range, and gateway. The administrator may provision thousands of these networks if desired. Additionally, the administrator can reserve a part -of the IP address space for non-CloudStack VMs and servers. +of the IP address space for non-CloudStack Instances and servers. Advanced Zone Public IP Addresses ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When advanced networking is used, the administrator can create -additional networks for use by the guests. These networks can span the +additional Public networks for use by the guests. These networks can span the zone and be available to all accounts, or they can be scoped to a single account, in which case only the named account may create guests that attach to these networks. The networks are defined by a VLAN ID, IP diff --git a/source/conceptsandterminology/index.rst b/source/conceptsandterminology/index.rst index 827233833d..4402fdf847 100644 --- a/source/conceptsandterminology/index.rst +++ b/source/conceptsandterminology/index.rst @@ -28,7 +28,7 @@ This is the Apache CloudStack installation guide. In this guide we first go thro .. toctree:: -Concepts and Terminolgy +Concepts and Terminology ------------------------ .. toctree:: :maxdepth: 2 @@ -37,6 +37,13 @@ Concepts and Terminolgy .. architecture: +Object Types in CloudStack +------------------------ +.. toctree:: + :maxdepth: 2 + + object_types + Choosing a Deployment Architecture ---------------------------------- .. toctree:: diff --git a/source/conceptsandterminology/locale/pot/administration_guide.pot b/source/conceptsandterminology/locale/pot/administration_guide.pot index 9d0aa3b801..19f84e4f2d 100644 --- a/source/conceptsandterminology/locale/pot/administration_guide.pot +++ b/source/conceptsandterminology/locale/pot/administration_guide.pot @@ -372,7 +372,7 @@ msgstr "" #: ../../administration_guide.rst:142 # f13f9e8ecc4148f18b10202f85506f55 -msgid "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." +msgid "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 ~cloud/.ssh/id_rsa." msgstr "" #: ../../administration_guide.rst:144 @@ -397,7 +397,7 @@ msgstr "" #: ../../administration_guide.rst:156 # dcc9b190ecda432bbde1662354d32bef -msgid "Format: ssh -i -p 3922 Example: root@management:~# ssh -i /var/lib/cloudstack/management/.ssh/id_rsa 172.16.0.250 -p 3922" +msgid "Format: ssh -i -p 3922 Example: root@management:~# ssh -i ~cloud/.ssh/id_rsa 172.16.0.250 -p 3922" msgstr "" #: ../../administration_guide.rst:160 @@ -779,7 +779,7 @@ msgstr "" #: ../../administration_guide.rst:331 # 3748d1e9df464087a1ffe1ff96240883 -msgid "Then you may power down the Host, re-use its IP address, re-install it, etc" +msgid "Then you may power down the Host, reuse its IP address, re-install it, etc" msgstr "" #: ../../administration_guide.rst:334 @@ -995,7 +995,7 @@ msgstr "" #: ../../administration_guide.rst:434 # 0e804d9f17db4c8a981a54fd41556317 -msgid "Fill in your desired over-provisioning multipliers in the fields CPU overcommit factor and RAM overcommit factor. The value which is intially shown in these fields is the default value inherited from the global configuration settings." +msgid "Fill in your desired over-provisioning multipliers in the fields CPU overcommit factor and RAM overcommit factor. The value which is initially shown in these fields is the default value inherited from the global configuration settings." msgstr "" #: ../../administration_guide.rst:437 diff --git a/source/conceptsandterminology/locale/pot/concepts.pot b/source/conceptsandterminology/locale/pot/concepts.pot index de31e099db..874ba784c0 100644 --- a/source/conceptsandterminology/locale/pot/concepts.pot +++ b/source/conceptsandterminology/locale/pot/concepts.pot @@ -248,7 +248,7 @@ msgstr "" #: ../../concepts.rst:134 # d33af50f42ee45deb987f9d2ade53d3b -msgid "Clusters: A cluster consists of one or more homogenous hosts and primary storage." +msgid "Clusters: A cluster consists of one or more homogeneous hosts and primary storage." msgstr "" #: ../../concepts.rst:135 diff --git a/source/conceptsandterminology/locale/pot/dev.pot b/source/conceptsandterminology/locale/pot/dev.pot index b83641edcd..a75b00a1cc 100644 --- a/source/conceptsandterminology/locale/pot/dev.pot +++ b/source/conceptsandterminology/locale/pot/dev.pot @@ -185,7 +185,7 @@ msgstr "" #: ../../dev.rst:136 # d443f5ac0cce419f98b4469aa4c74efc -msgid "To show how to sign a request, we will re-use the previous example." +msgid "To show how to sign a request, we will reuse the previous example." msgstr "" #: ../../dev.rst:140 diff --git a/source/conceptsandterminology/locale/pot/developer_guide.pot b/source/conceptsandterminology/locale/pot/developer_guide.pot index 0c8252b250..7dfd0042fc 100644 --- a/source/conceptsandterminology/locale/pot/developer_guide.pot +++ b/source/conceptsandterminology/locale/pot/developer_guide.pot @@ -323,7 +323,7 @@ msgstr "" #: ../../developer_guide.rst:334 # d99c1e63a66443539d663a0cba7beca0 -msgid "The Installing from source section will only get you to the point of runnign the management server, it does not get you any hypervisors. The simulator section gets you a simulated datacenter for testing. With DevCloud you can run at least one hypervisor and add it to your management server the way you would a real physical machine." +msgid "The Installing from source section will only get you to the point of running the management server, it does not get you any hypervisors. The simulator section gets you a simulated datacenter for testing. With DevCloud you can run at least one hypervisor and add it to your management server the way you would a real physical machine." msgstr "" #: ../../developer_guide.rst:340 @@ -443,12 +443,12 @@ msgstr "" #: ../../developer_guide.rst:460 # 7c104d4cd0fe475e863b91f53449a5c5 -msgid "The CloudStack API is a query based API using http that return results in XML or JSON. It is used to implement the default web UI. This API is not a standard like `OGF OCCI `__ or `DMTF CIMI `__ but is easy to learn. Mapping exists between the AWS API and the CloudStack API as will be seen in the next section. Recently a Google Compute Engine interface was also developed that maps the GCE REST API to the CloudStack API described here. The API `docs `__ are a good start to learn the extent of the API. Multiple clients exist on `github `__ to use this API, you should be able to find one in your favorite language. The reference documentation for the API and changes that might occur from version to version is availble `on-line `__. This short section is aimed at providing a quick summary to give you a base understanding of how to use this API. As a quick start, a good way to explore the API is to navigate the dashboard with a firebug console (or similar developer console) to study the queries." +msgid "The CloudStack API is a query based API using http that return results in XML or JSON. It is used to implement the default web UI. This API is not a standard like `OGF OCCI `__ or `DMTF CIMI `__ but is easy to learn. Mapping exists between the AWS API and the CloudStack API as will be seen in the next section. Recently a Google Compute Engine interface was also developed that maps the GCE REST API to the CloudStack API described here. The API `docs `__ are a good start to learn the extent of the API. Multiple clients exist on `GitHub `__ to use this API, you should be able to find one in your favorite language. The reference documentation for the API and changes that might occur from version to version is available `on-line `__. This short section is aimed at providing a quick summary to give you a base understanding of how to use this API. As a quick start, a good way to explore the API is to navigate the dashboard with a firebug console (or similar developer console) to study the queries." msgstr "" #: ../../developer_guide.rst:481 # 0bcb8dd851254f9b9b0240917b405d84 -msgid "In a succint statement, the CloudStack query API can be used via http GET requests made against your cloud endpoint (e.g http://localhost:8080/client/api). The API name is passed using the ``command`` key and the various parameters for this API call are passed as key value pairs. The request is signed using the access key and secret key of the user making the call. Some calls are synchronous while some are asynchronous, this is documented in the API `docs `__. Asynchronous calls return a ``jobid``, the status and result of a job can be queried with the ``queryAsyncJobResult`` call. Let's get started and give an example of calling the ``listUsers`` API in Python." +msgid "In a succinct statement, the CloudStack query API can be used via http GET requests made against your cloud endpoint (e.g http://localhost:8080/client/api). The API name is passed using the ``command`` key and the various parameters for this API call are passed as key value pairs. The request is signed using the access key and secret key of the user making the call. Some calls are synchronous while some are asynchronous, this is documented in the API `docs `__. Asynchronous calls return a ``jobid``, the status and result of a job can be queried with the ``queryAsyncJobResult`` call. Let's get started and give an example of calling the ``listUsers`` API in Python." msgstr "" #: ../../developer_guide.rst:493 @@ -458,7 +458,7 @@ msgstr "" #: ../../developer_guide.rst:504 # f06d2f79776845b69c69945a988dc02d -msgid "Open a Python shell and import the basic modules necessary to make the request. Do note that this request could be made many different ways, this is just a low level example. The ``urllib*`` modules are used to make the http request and do url encoding. The ``hashlib`` module gives us the sha1 hash function. It used to geenrate the ``hmac`` (Keyed Hashing for Message Authentication) using the secretkey. The result is encoded using the ``base64`` module." +msgid "Open a Python shell and import the basic modules necessary to make the request. Do note that this request could be made many different ways, this is just a low level example. The ``urllib*`` modules are used to make the http request and do url encoding. The ``hashlib`` module gives us the sha1 hash function. It used to generate the ``hmac`` (Keyed Hashing for Message Authentication) using the secretkey. The result is encoded using the ``base64`` module." msgstr "" #: ../../developer_guide.rst:524 @@ -483,12 +483,12 @@ msgstr "" #: ../../developer_guide.rst:586 # 34385cfcf355434bbfec59e948728211 -msgid "All the clients that you will find on github will implement this signature technique, you should not have to do it by hand. Now that you have explored the API through the UI and that you understand how to make low level calls, pick your favorite client of use `CloudMonkey `__. CloudMonkey is a sub-project of Apache CloudStack and gives operators/developers the ability to use any of the API methods. It has nice auto-completion and help feature as well as an API discovery mechanism since 4.2." +msgid "All the clients that you will find on GitHub will implement this signature technique, you should not have to do it by hand. Now that you have explored the API through the UI and that you understand how to make low level calls, pick your favorite client of use `CloudMonkey `__. CloudMonkey is a sub-project of Apache CloudStack and gives operators/developers the ability to use any of the API methods. It has nice auto-completion and help feature as well as an API discovery mechanism since 4.2." msgstr "" #: ../../developer_guide.rst:598 # 4bf1c04a89934aca9d24a5a585888739 -msgid "While the native CloudStack API is not a standard, CloudStack provides a AWS EC2 compatible interface. It has the great advantage that existing tools written with EC2 libraries can be re-used against a CloudStack based cloud. In the installation books we described how to run this interface from installing packages. In this section we show you how to compile the interface with ``maven`` and test it with Python boto module." +msgid "While the native CloudStack API is not a standard, CloudStack provides a AWS EC2 compatible interface. It has the great advantage that existing tools written with EC2 libraries can be reused against a CloudStack based cloud. In the installation books we described how to run this interface from installing packages. In this section we show you how to compile the interface with ``maven`` and test it with Python boto module." msgstr "" #: ../../developer_guide.rst:606 diff --git a/source/conceptsandterminology/locale/pot/networking.pot b/source/conceptsandterminology/locale/pot/networking.pot index edb353bc1d..8655112ad7 100644 --- a/source/conceptsandterminology/locale/pot/networking.pot +++ b/source/conceptsandterminology/locale/pot/networking.pot @@ -744,7 +744,7 @@ msgstr "" #: ../../networking/nicira-plugin.rst:7 # 0c134c3d04de4ba49f31e0c3f0108144 -msgid "The Nicira NVP plugin adds Nicira NVP as one of the available SDN implementations in CloudStack. With the plugin an exisiting Nicira NVP setup can be used by CloudStack to implement isolated guest networks and to provide additional services like routing and NAT." +msgid "The Nicira NVP plugin adds Nicira NVP as one of the available SDN implementations in CloudStack. With the plugin an existing Nicira NVP setup can be used by CloudStack to implement isolated guest networks and to provide additional services like routing and NAT." msgstr "" #: ../../networking/nicira-plugin.rst:13 @@ -1810,7 +1810,7 @@ msgstr "" #: ../../networking/vxlan.rst:152 # 6856ea7ca74549fb91a97823fda39f40 -msgid "This plugin requires an IPv4 address on the KVM host to terminate and originate VXLAN traffic. The address should be assinged to a physical interface or a bridge interface bound to a physical interface. Both a private address or a public address are fine for the purpose. It is not required to be in the same subnet for all hypervisors in a zone, but they should be able to reach each other via IP multicast with UDP/8472 port. A name of a physical interface or a name of a bridge interface bound to a physical interface can be used as a traffic label. Physical interface name fits for almost all cases, but if physical interface name differs per host, you may use a bridge to set a same name. If you would like to use a bridge name as a traffic label, you may create a bridge in this way." +msgid "This plugin requires an IPv4 address on the KVM host to terminate and originate VXLAN traffic. The address should be assigned to a physical interface or a bridge interface bound to a physical interface. Both a private address or a public address are fine for the purpose. It is not required to be in the same subnet for all hypervisors in a zone, but they should be able to reach each other via IP multicast with UDP/8472 port. A name of a physical interface or a name of a bridge interface bound to a physical interface can be used as a traffic label. Physical interface name fits for almost all cases, but if physical interface name differs per host, you may use a bridge to set a same name. If you would like to use a bridge name as a traffic label, you may create a bridge in this way." msgstr "" #: ../../networking/vxlan.rst:165 @@ -1866,7 +1866,7 @@ msgstr "" #: ../../networking/vxlan.rst:298 # 494b6216726d4b41ac1143c03c93ede2 -msgid "These iptable settings are not persistent accross reboots, we have to save them first." +msgid "These iptable settings are not persistent across reboots, we have to save them first." msgstr "" #: ../../networking/vxlan.rst:306 diff --git a/source/conceptsandterminology/network_setup.rst b/source/conceptsandterminology/network_setup.rst index feed58a73b..f5576af969 100644 --- a/source/conceptsandterminology/network_setup.rst +++ b/source/conceptsandterminology/network_setup.rst @@ -55,7 +55,7 @@ VPN support No Yes Port forwarding Physical Physical and Virtual 1:1 NAT Physical Physical and Virtual Source NAT No Physical and Virtual -Userdata Yes Yes +User data Yes Yes Network usage monitoring sFlow / netFlow at physical router Hypervisor and Virtual Router DNS and DHCP Yes Yes ========================= =================================== =============================== @@ -287,7 +287,7 @@ External Guest Firewall Integration for Juniper SRX (Optional) CloudStack provides for direct management of the Juniper SRX series of firewalls. This enables CloudStack to establish static NAT mappings from -public IPs to guest VMs, and to use the Juniper device in place of the +public IPs to Guest Instances, and to use the Juniper device in place of the virtual router for firewall services. You can have one or more Juniper SRX per zone. This feature is optional. If Juniper integration is not provisioned, CloudStack will use the virtual router for these services. @@ -482,9 +482,9 @@ Guidelines - Use the public IP address range from a single subnet. You cannot add IP addresses from different subnets. -- Only one ASA instance per VLAN is allowed because multiple VLANS +- Only one ASA Instance per VLAN is allowed because multiple VLANS cannot be trunked to ASA ports. Therefore, you can use only one ASA - instance in a guest network. + Instance in a guest network. - Only one Cisco VNMC per zone is allowed. @@ -538,7 +538,7 @@ Prerequisites Typically, you create a pool of ASA 1000v appliances and register them with CloudStack. - Specify the following while setting up a Cisco ASA 1000v instance: + Specify the following while setting up a Cisco ASA 1000v Instance: - VNMC host IP. @@ -558,7 +558,7 @@ Prerequisites #. Register Cisco ASA 1000v with VNMC. - After Cisco ASA 1000v instance is powered on, register VNMC from the + After Cisco ASA 1000v Instance is powered on, register VNMC from the ASA console. @@ -569,11 +569,11 @@ Using Cisco ASA 1000v Services See `“Prerequisites” <#prerequisites>`_. -#. Add a VNMC instance. +#. Add a VNMC Instance. See `“Adding a VNMC Instance” <#adding-a-vnmc-instance>`_. -#. Add a ASA 1000v instance. +#. Add a ASA 1000v Instance. See :ref:`adding-an-asa-1000v-instance`. @@ -610,9 +610,9 @@ Adding a VNMC Instance #. Click the Add VNMC Device and provide the following: - - Host: The IP address of the VNMC instance. + - Host: The IP address of the VNMC Instance. - - Username: The user name of the account on the VNMC instance that + - Username: The user name of the account on the VNMC Instance that CloudStack should use. - Password: The password of the account. @@ -645,14 +645,14 @@ Adding an ASA 1000v Instance #. Click the Add CiscoASA1000v Resource and provide the following: - - **Host**: The management IP address of the ASA 1000v instance. The + - **Host**: The management IP address of the ASA 1000v Instance. The IP address is used to connect to ASA 1000V. - **Inside Port Profile**: The Inside Port Profile configured on Cisco Nexus1000v dvSwitch. - **Cluster**: The VMware cluster to which you are adding the ASA - 1000v instance. + 1000v Instance. Ensure that the cluster is Cisco Nexus 1000v dvSwitch enabled. @@ -668,7 +668,7 @@ offering as follows: #. Log in to the CloudStack UI as a user or admin. -#. Naviagte to Service Offerings and choose Network OfferingPublic IP Addresses. +#. Navigate to Service Offerings and choose Network OfferingPublic IP Addresses. #. Click Add Network Offering. @@ -689,7 +689,7 @@ offering as follows: - **Persistent**: Indicate whether the guest network is persistent or not. The network that you can provision without having to - deploy a VM on it is termed persistent network. + deploy an Instance on it is termed persistent network. - **VPC**: This option indicate whether the guest network is Virtual Private Cloud-enabled. A Virtual Private Cloud (VPC) is a private, @@ -830,7 +830,7 @@ management: #. Click OK. The installation and provisioning of the external load balancer is -finished. You can proceed to add VMs and NAT or load balancing rules. +finished. You can proceed to add Instances and NAT or load balancing rules. Management Server Load Balancing @@ -895,10 +895,10 @@ Storage Network Topology Requirements The secondary storage NFS export is mounted by the secondary storage VM. Secondary storage traffic goes over the management traffic network, even -if there is a separate storage network. Primary storage traffic goes -over the storage network, if available. If you choose to place secondary -storage NFS servers on the storage network, you must make sure there is -a route from the management traffic network to the storage network. +if there is a separate Storage Network. Primary storage traffic goes +over the Storage Network, if available. If you choose to place secondary +storage NFS servers on the Storage Network, you must make sure there is +a route from the management traffic network to the Storage Network. External Firewall Topology Requirements @@ -1020,10 +1020,10 @@ To set up the integration between CloudStack and Traffic Sentinel: Setting Zone VLAN and Running VM Maximums ----------------------------------------- -In the external networking case, every VM in a zone must have a unique +In the external networking case, every Instance in a zone must have a unique guest IP address. There are two variables that you need to consider in determining how to configure CloudStack to support this: how many Zone -VLANs do you expect to have and how many VMs do you expect to have +VLANs do you expect to have and how many Instances do you expect to have running in the Zone at any one time. Use the following table to determine how to configure CloudStack for @@ -1031,14 +1031,14 @@ your deployment. .. cssclass:: table-striped table-bordered table-hover -=============== ============================ ================== -guest.vlan.bits Maximum Running VMs per Zone Maximum Zone VLANs -=============== ============================ ================== -12 4096 4094 -11 8192 2048 -10 16384 1024 -10 32768 512 -=============== ============================ ================== +=============== ================================== ================== +guest.vlan.bits Maximum Running Instances per Zone Maximum Zone VLANs +=============== ================================== ================== +12 4096 4094 +11 8192 2048 +10 16384 1024 +10 32768 512 +=============== ================================== ================== Based on your deployment's needs, choose the appropriate value of guest.vlan.bits. Set it as described in Edit the Global Configuration diff --git a/source/conceptsandterminology/object_types.rst b/source/conceptsandterminology/object_types.rst new file mode 100644 index 0000000000..20fafd5a67 --- /dev/null +++ b/source/conceptsandterminology/object_types.rst @@ -0,0 +1,59 @@ +.. 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. + + + +All Object Types in Apache CloudStack +------------------------------------- + +.. cssclass:: table-striped table-bordered table-hover + +========================= =================================== +Object Name Description +========================= =================================== + Account A CloudStack account is a group of users. An account is used to manage users and resources. Each resource is owned by an account. Resources can be shared between accounts within the same domain. + Affinity Group An affinity group is a way to group instances together on the same host or to keep them apart. Affinity groups are defined at the account level and can be applied to instances at the time of deployment. + Alert Alerts are used to notify administrators of system events. Alerts can be generated for various events + Cluster A cluster is a collection of hosts. A cluster contains hosts that are managed by the same hypervisor. A cluster is contained within a zone and can contain primary storage. + Disk Offering A disk offering defines the characteristics of a disk volume. A disk offering specifies the size of the disk volume and whether it is local or shared storage. + Domain A domain is a hierarchical administrative unit within CloudStack. Domains are used to partition the CloudStack environment into separate sections. Each domain can have its own administrators, users, and resources. Domains can be nested to create a hierarchy. + Event Events are used to track system activity. Events are generated for various actions taken by users and administrators. + Global Settings Global settings are configuration parameters that apply to the entire CloudStack environment. + Host A host is a physical server that runs the hypervisor software. Hosts are grouped into clusters and are contained within a zone. + Hypervisor A hypervisor is the software that enables virtualization. CloudStack supports several hypervisors, including KVM, XenServer, VMware, and Hyper-V. + Instance An Instance is a virtual machine that runs on a host. Historically they were called Virtual Machines, so CloudStack APIs are named after that. Instances are created from templates and can be managed by users and administrators. + IP Address An IP address is a unique identifier assigned to an instance or a network interface. IP addresses can be either public or private. + ISO Image An ISO image is a disk image that contains an operating system or other software. ISO images can be used to create instances or to install software on existing instances. + Load Balancer A load balancer is a device that distributes network traffic across multiple instances. Load balancers can be used to improve performance and availability. + Network A Network is a virtual network that connects instances and other resources. Networks can be either isolated or shared. + Network Offering A network offering defines the characteristics of a network. A network offering specifies the type of network, the services it provides, and the traffic types it supports. + Physical Network A physical network is a representation of the underlying physical network infrastructure. Physical networks can be used to define how virtual networks are mapped to physical networks. + Pod A pod is a collection of hosts within a zone. Pods are used to group hosts that are in the same physical location. + Primary Storage Primary storage is the storage that is used to store virtual machine disk volumes. Primary storage can be either local or shared storage. + Project A project is a way to group resources together for a specific purpose. Projects can be used to manage resources for a specific team or application. + Resource Tag Resource tags are labels that can be applied to resources to help organize and manage them. + Secondary Storage Secondary storage is the storage that is used to store templates, ISO images, and snapshots. Secondary storage is typically shared storage. + Security Group A security group is a virtual firewall that controls inbound and outbound traffic to instances. Security groups can be used to restrict access to instances based on IP address, port, and protocol. + Service Offering A service offering defines the characteristics of an instance. A service offering specifies the CPU, memory, and other resources that are allocated to an instance. + Snapshot A snapshot is a point-in-time copy of a disk volume. Snapshots can be used to back up data or to create new disk volumes. + SSH Key Pair An SSH key pair is a pair of cryptographic keys that are used to authenticate users when they connect to instances via SSH. + Storage Pool A storage pool is a collection of storage resources that can be used to store virtual machine disk volumes. Storage pools can be either local or shared storage. + Template A Template is a pre-configured disk image that contains an operating system and other software. Templates can be used to create instances. + User A User is an individual who has access to the CloudStack environment. Users can be assigned to accounts and can have different roles and permissions. + VLAN A VLAN (Virtual Local Area Network) is a logical partition of a physical network. VLANs can be used to isolate network traffic and improve security. + VPC A VPC (Virtual Private Cloud) is a virtual network that is isolated from other networks. VPCs can be used to create a private cloud environment within CloudStack. + Volume A volume is a virtual disk that can be attached to an instance. Volumes can be created from templates, snapshots, or other volumes. + Zone A zone is a top-level container for resources. A zone contains clusters, pods, and primary storage. Zones can be used to represent different geographical locations or different environments (e.g., production, development). +========================= =================================== diff --git a/source/conceptsandterminology/storage_setup.rst b/source/conceptsandterminology/storage_setup.rst index 24e6706a50..cbd238c85d 100644 --- a/source/conceptsandterminology/storage_setup.rst +++ b/source/conceptsandterminology/storage_setup.rst @@ -56,9 +56,9 @@ Small-Scale Setup In a small-scale setup, a single NFS server can function as both primary and secondary storage. The NFS server must export two separate shares, one for primary storage and the other for secondary storage. This -could be a VM or physical host running an NFS service on a Linux OS or a virtual software appliance. Disk +could be an Instance or physical host running an NFS service on a Linux OS or a virtual software appliance. Disk and network performance are still important in a small scale setup to get a good experience when deploying, -running or snapshotting VMs. +running or snapshotting Instances. Large-Scale Setup @@ -66,14 +66,14 @@ Large-Scale Setup In large-scale environments primary and secondary storage typically consist of independent physical storage arrays. -Primary storage is likely to have to support mostly random read/write I/O once a template has been +Primary storage is likely to have to support mostly random read/write I/O once a Template has been deployed. Secondary storage is only going to experience sustained sequential reads or writes. -In clouds which will experience a large number of users taking snapshots or deploying VMs at the +In clouds which will experience a large number of users taking Snapshots or deploying Instances at the same time, secondary storage performance will be important to maintain a good user experience. It is important to start the design of your storage with the a rough profile of the workloads which it will -be required to support. Care should be taken to consider the IOPS demands of your guest VMs as much as the +be required to support. Care should be taken to consider the IOPS demands of your Guest Instances as much as the volume of data to be stored and the bandwidth (MB/s) available at the storage interfaces. Storage Architecture @@ -89,10 +89,10 @@ Local Storage ============= Local storage works best for pure 'cloud-era' workloads which rarely need to be migrated between storage -pools and where HA of individual VMs is not required. As SSDs become more mainstream/affordable, local -storage based VMs can now be served with the size of IOPS which previously could only be generated by +pools and where HA of individual Instances is not required. As SSDs become more mainstream/affordable, local +storage based Instances can now be served with the size of IOPS which previously could only be generated by large arrays with 10s of spindles. Local storage is highly scalable because as you add hosts you would -add the same proportion of storage. Local Storage is relatively inefficent as it can not take advantage +add the same proportion of storage. Local Storage is relatively inefficient as it can not take advantage of linked clones or any deduplication. @@ -110,7 +110,7 @@ host fail. These shared storage arrays often have the ability to create 'tiers' say large SATA disks, 15k SAS disks and SSDs. These differently performing tiers can then be presented as different offerings to users. The sizing of an array should take into account the IOPS required by the workload as well as the volume -of data to be stored. One should also consider the number of VMs which a storage array will be expected +of data to be stored. One should also consider the number of Instances which a storage array will be expected to support, and the maximum network bandwidth possible through the controllers. @@ -144,8 +144,8 @@ that it is the hypervisor itself that communicates with the primary storage, the server only communicates with the host hypervisor. Now, all hypervisors communicate with the outside world via some kind of management interface – think VMKernel port on ESXi or ‘Management Interface’ on XenServer. As the CloudStack management server needs to communicate with the hypervisor in the host, -this management interface must be on the CloudStack ‘management’ or ‘private’ network. There may be -other interfaces configured on your host carrying guest and public traffic to/from VMs within the hosts +this management interface must be on the CloudStack ‘management’ or ‘private’ Network. There may be +other interfaces configured on your host carrying guest and public traffic to/from Instances within the hosts but the hypervisor itself doesn’t/can’t communicate over these interfaces. |hypervisorcomms.png| @@ -163,7 +163,7 @@ The logical reasoning which explains how this splitting of traffic works is as f #. The mechanism to create an additional interface that the hypervisor can use is to create an additional management interface #. So that the hypervisor can differentiate between the management interfaces they have to be in different (non-overlapping) subnets #. In order for the ‘primary storage’ management interface to communicate with the primary storage, the interfaces on the primary storage arrays must be in the same CIDR as the ‘primary storage’ management interface. -#. Therefore the primary storage must be in a different subnet to the management network +#. Therefore the primary storage must be in a different subnet to the Management Network |subnetting storage.png| *Figure 2*: Subnetting of Storage Traffic @@ -215,7 +215,7 @@ operating system version. Adjust the above command to suit your deployment needs. -- **Limiting NFS export.** It is highly recommended that you limit the NFS export to a particular subnet by specifying a subnet mask (e.g.,”192.168.1.0/24”). By allowing access from only within the expected cluster, you avoid having non-pool member mount the storage. The limit you place must include the management network(s) and the storage network(s). If the two are the same network then one CIDR is sufficient. If you have a separate storage network you must provide separate CIDR’s for both or one CIDR that is broad enough to span both. +- **Limiting NFS export.** It is highly recommended that you limit the NFS export to a particular subnet by specifying a subnet mask (e.g.,”192.168.1.0/24”). By allowing access from only within the expected cluster, you avoid having non-pool member mount the storage. The limit you place must include the Management Network(s) and the Storage Network(s). If the two are the same network then one CIDR is sufficient. If you have a separate Storage Network you must provide separate CIDR’s for both or one CIDR that is broad enough to span both. The following is an example with separate CIDRs: @@ -336,8 +336,8 @@ Now you can set up /export as an NFS share. from only within the expected cluster, you avoid having non-pool member mount the storage and inadvertently delete all its data. The limit you place must include the management network(s) and the - storage network(s). If the two are the same network then one CIDR is - sufficient. If you have a separate storage network you must provide + Storage Network(s). If the two are the same network then one CIDR is + sufficient. If you have a separate Storage Network you must provide separate CIDRs for both or one CIDR that is broad enough to span both. diff --git a/source/conf.py b/source/conf.py index 55fb01d176..fe4543b671 100644 --- a/source/conf.py +++ b/source/conf.py @@ -20,13 +20,13 @@ # -- Project information ----------------------------------------------------- project = 'Apache CloudStack' -copyright = '2012-2021, Apache Foundation' +copyright = '2012-2025, Apache Foundation' author = 'Apache CloudStack Project' # The short X.Y version -version = '4.16' +version = '4.22' # The full version, including alpha/beta/rc tags -release = '4.16.0.0' +release = '4.22.0.0' rst_epilog = """ .. include:: /_global.rst @@ -45,6 +45,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', + 'sphinx.ext.autosectionlabel', ] # Add any paths that contain templates here, relative to this directory. diff --git a/source/developersguide/alloc.rst b/source/developersguide/alloc.rst index 00ce8c9760..33dc95d82a 100644 --- a/source/developersguide/alloc.rst +++ b/source/developersguide/alloc.rst @@ -24,10 +24,10 @@ allocate guest virtual disk images. These are following categories of allocators currently supported: - HostAllocators - Allows you to create custom rules to determine which - physical host to allocate the guest virtual machines on. + physical host to allocate the Guest Instances on. - StoragePoolAllocators - Allows you to create custom rules to - determine which storage pool to allocate the guest virtual machines + determine which storage pool to allocate the Guest Instances on. @@ -46,7 +46,7 @@ The interface defines the following two methods. :: /** - * Checks if the VM can be upgraded to the specified ServiceOffering + * Checks if the Instance can be upgraded to the specified ServiceOffering * @param UserVm vm * @param ServiceOffering offering * @return boolean true if the VM can be upgraded @@ -55,7 +55,7 @@ The interface defines the following two methods. publicboolean isVirtualMachineUpgradable(final UserVm vm, final ServiceOffering offering); /** - * Determines which physical hosts are suitable to allocate the guest virtual machines on + * Determines which physical hosts are suitable to allocate the Guest Instances on * * @paramVirtualMachineProfile vmProfile * @paramDeploymentPlan plan @@ -76,35 +76,35 @@ Input Parameters for the method ‘HostAllocator :: allocateTo’ *com.cloud.vm.VirtualMachineProfile vmProfile* -VirtualMachineProfile describes one virtual machine. This allows the +VirtualMachineProfile describes one Instance. This allows the adapters like Allocators to process the information in the virtual -machine and make determinations on what the virtual machine profile +machine and make determinations on what the Instance profile should look like before it is actually started on the hypervisor. HostAllocators can make use of the following information present in the VirtualMachineProfile: - The ServiceOffering that specifies configuration like requested CPU - speed, RAM etc necessary for the guest VM. + speed, RAM etc necessary for the Guest Instance. -- The VirtualMachineTemplate, the template to be used to start the VM. +- The VirtualMachineTemplate, the Template to be used to start the Instance. *com.cloud.deploy.DeploymentPlan plan* DeploymentPlan should specify: -- dataCenterId: The data center the VM should deploy in +- dataCenterId: The data center the Instance should deploy in -- podId: The pod the Vm should deploy in; null if no preference +- podId: The pod the Instance should deploy in; null if no preference -- clusterId: The cluster the VM should deploy in; null if no preference +- clusterId: The cluster the Instance should deploy in; null if no preference -- poolId: The storage pool the VM should be created in; null if no +- poolId: The storage pool the Instance should be created in; null if no preference *com.cloud.host.Host.Type type* -Type of the Host needed for this guest VM. Currently +Type of the Host needed for this Guest Instance. Currently com.cloud.host.Host.Type interface defines the following Host types: - Storage @@ -122,7 +122,7 @@ com.cloud.host.Host.Type interface defines the following Host types: *com.cloud.deploy.DeploymentPlanner.ExcludeList avoid* The ExcludeList specifies what datacenters, pods, clusters, hosts, -storagePools should not be considered for allocating this guest VM. +storagePools should not be considered for allocating this Guest Instance. HostAllocators should avoid the hosts that are mentioned in ExcludeList.hostIds. @@ -138,7 +138,7 @@ ExcludeList.hostIds. *int returnUpTo* -This specifies return up to that many available hosts for this guest VM. +This specifies return up to that many available hosts for this Guest Instance. To get all possible hosts, set this value to -1. @@ -152,7 +152,7 @@ hosts in the specified datacenter, Pod, Cluster and considering the given ServiceOffering requirements. If returnUpTo = 1, this allocator would return the first Host that fits -the requirements of the guest VM. +the requirements of the Guest Instance. Loading a custom HostAllocator @@ -198,7 +198,7 @@ A custom StoragePoolAllocator can be written by implementing the :: /** - * Determines which storage pools are suitable for the guest virtual machine + * Determines which storage pools are suitable for the guest Instance * @param DiskProfile dskCh * @param VirtualMachineProfile vmProfile * @param DeploymentPlan plan @@ -227,36 +227,36 @@ searching for a storage pool. *com.cloud.vm.VirtualMachineProfile vmProfile* -VirtualMachineProfile describes one virtual machine. This allows the +VirtualMachineProfile describes one Instance. This allows the adapters like Allocators to process the information in the virtual -machine and make determinations on what the virtual machine profile +machine and make determinations on what the Instance profile should look like before it is actually started on the hypervisor. StoragePoolAllocators can make use of the following information present in the VirtualMachineProfile: -- The VirtualMachine instance that specifies properties of the guest - VM. +- The VirtualMachine Instance that specifies properties of the guest + Instance. -- The VirtualMachineTemplate, the template to be used to start the VM. +- The VirtualMachineTemplate, the Template to be used to start the Instance. *com.cloud.deploy.DeploymentPlan plan* DeploymentPlan should specify: -- dataCenterId: The data center the VM should deploy in +- dataCenterId: The data center the Instance should deploy in -- podId: The pod the VM should deploy in; null if no preference +- podId: The pod the Instance should deploy in; null if no preference -- clusterId: The cluster the VM should deploy in; null if no preference +- clusterId: The cluster the Instance should deploy in; null if no preference -- poolId: The storage pool the VM should be created in; null if no +- poolId: The storage pool the Instance should be created in; null if no preference *com.cloud.deploy.DeploymentPlanner.ExcludeList avoid* The ExcludeList specifies what datacenters, pods, clusters, hosts, -storagePools should not be considered for allocating this guest VM. +storagePools should not be considered for allocating this Guest Instance. StoragePoolAllocators should avoid the pools that are mentioned in ExcludeList.poolIds @@ -272,7 +272,7 @@ ExcludeList.poolIds *int returnUpTo* -This specifies return up to that many available pools for this guest VM +This specifies return up to that many available pools for this Guest Instance To get all possible pools, set this value to -1 @@ -286,7 +286,7 @@ available pools in the specified datacenter, Pod, Cluster and considering the given DiskProfile characteristics. If returnUpTo = 1, this allocator would return the first Storage Pool -that fits the requirements of the guest VM. +that fits the requirements of the Guest Instance. Loading a custom StoragePoolAllocator diff --git a/source/developersguide/ansible.rst b/source/developersguide/ansible.rst index 21eb38b7a4..f6bd73a0df 100644 --- a/source/developersguide/ansible.rst +++ b/source/developersguide/ansible.rst @@ -17,11 +17,6 @@ Deploying CloudStack with Ansible ================================= -In this article, `Paul Angus `__ Cloud -Architect at ShapeBlue takes a look at using Ansible to Deploy an -Apache CloudStack cloud.  - - What is Ansible --------------- @@ -68,7 +63,7 @@ So let’s see something For this example we’re going to create an Ansible server which will then deploy a CloudStack server. Both of these servers will be CentOS 6.4 -virtual machines. +Instances. Installing Ansible @@ -195,7 +190,7 @@ the file will look like this: yum: name=libselinux-python state=present - - name: Ensure cloudstack specfic my.cnf lines are present + - name: Ensure cloudstack specific my.cnf lines are present lineinfile: dest=/etc/my.cnf regexp=’$item’ insertafter=”symbolic-links=0″ line=’$item’ @@ -239,7 +234,7 @@ the file will look like this: This needs to be saved as `/etc/ansible/roles/mysql/tasks/main.yml` As explained earlier, this playbook in fact describes the state of the -host rather than setting out commands to be run. For instance, we +host rather than setting out commands to be run. For Instance, we specify certain lines which must be in the my.cnf file and allow Ansible to decide whether or not it needs to add them. @@ -272,7 +267,7 @@ For the management server role we create a main.yml task like this:   yum: name=libselinux-python state=present - - name: Ensure the Apache Cloudstack Repo file exists as per template + - name: Ensure the Apache Cloudstack Repo file exists as per Template   template: src=cloudstack.repo.j2 dest=/etc/yum.repos.d/cloudstack.repo @@ -299,9 +294,13 @@ For the management server role we create a main.yml task like this: Save this as `/etc/ansible/roles/cloudstack-management/tasks/main.yml` -Now we have some new elements to deal with. The Ansible template module +.. note:: In a production environment, selinux should be set to enforcing + and the necessary selinux policies are created to allow the + services to run. + +Now we have some new elements to deal with. The Ansible Template module uses Jinja2 based templating.  As we’re doing a simplified example here, -the Jinja template for the cloudstack.repo won’t have any variables in +the Jinja Template for the cloudstack.repo won’t have any variables in it, so it would simply look like this: :: @@ -340,7 +339,7 @@ There are some more variables here for us to declare later. System VM Templates: -------------------- -Finally we would want to seed the system VM templates into the secondary +Finally we would want to seed the system VM Templates into the secondary storage.  The playbook for this would look as follows: :: @@ -355,19 +354,19 @@ storage.  The playbook for this would look as follows: - name: Seed secondary storage   command: - /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2 -h kvm -F + /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloudstack.org/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2 -h kvm -F   command: - /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 -h xenserver -F + /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloudstack.org/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 -h xenserver -F   command: - /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-4.2-vh7.ov -h vmware -F + /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloudstack.org/templates/4.2/systemvmtemplate-4.2-vh7.ov -h vmware -F Save this as `/etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml` Again, there isn’t a CloudStack module so Ansible will always run this -even if the secondary storage already has the templates in it. +even if the secondary storage already has the Templates in it.   Bringing it all together diff --git a/source/developersguide/dev.rst b/source/developersguide/dev.rst index f35333c653..67aceb1415 100644 --- a/source/developersguide/dev.rst +++ b/source/developersguide/dev.rst @@ -32,8 +32,8 @@ To get started using the CloudStack API, you should have the following: - URL of the CloudStack server you wish to integrate with. -- Both the API Key and Secret Key for an account. This should have been - generated by the administrator of the cloud instance and given to +- Both the API Key and Secret Key for an Account. This should have been + generated by the administrator of the cloud Instance and given to you. - Familiarity with HTTP GET/POST and query strings. @@ -55,8 +55,8 @@ The CloudStack API supports three access roles: #. Domain Admin. Access to only the virtual resources of the clouds that belong to the administrator’s domain. -#. User. Access to only the features that allow management of the user’s - virtual instances, storage, and network. +#. User. Access to only the features that allow management of the User’s + Instances, storage, and Network. API Reference Documentation @@ -79,7 +79,7 @@ the following whether in HTTP or HTTPS: example, http://www.example.com:8080/client/api) - Command: The web services command you wish to execute, such as start - a virtual machine or create a disk volume + an Instance or create a disk volume - Parameters: Any additional required or optional parameters for the command @@ -103,11 +103,11 @@ Or in a more readable format: 7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ 8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D -The first line is the CloudStack API URL. This is the Cloud instance you +The first line is the CloudStack API URL. This is the Cloud Instance you wish to interact with. The second line refers to the command you wish to execute. In our -example, we are attempting to deploy a fresh new virtual machine. It is +example, we are attempting to deploy a fresh new Instance. It is preceded by a (?) to separate itself from the CloudStack API URL. Lines 3-6 are the parameters for this given command. To see the command @@ -115,10 +115,10 @@ and its request parameters, please refer to the appropriate section in the CloudStack API documentation. Each parameter field-value pair (field=value) is preceded by an ampersand character (&). -Line 7 is the user API Key that uniquely identifies the account. See +Line 7 is the User API Key that uniquely identifies the Account. See Signing API Requests on page 7. -Line 8 is the signature hash created to authenticate the user account +Line 8 is the signature hash created to authenticate the User Account executing the API command. @@ -129,10 +129,10 @@ Whether you access the CloudStack API with HTTP or HTTPS, it must still be signed so that CloudStack can verify the caller has been authenticated and authorized to execute the command. Make sure that you have both the API Key and Secret Key provided by the CloudStack -administrator for your account before proceeding with the signing +administrator for your Account before proceeding with the signing process. -To show how to sign a request, we will re-use the previous example. +To show how to sign a request, we will reuse the previous example. .. parsed-literal:: @@ -154,7 +154,7 @@ Breaking this down, we have several distinct parts to this URL. /client/api? - Command String: This part of the query string comprises of the - command, its parameters, and the API Key that identifies the account. + command, its parameters, and the API Key that identifies the Account. .. note:: As with all query string parameters of field-value pairs, the "field" @@ -166,7 +166,7 @@ Breaking this down, we have several distinct parts to this URL. command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ - Signature: This is the signature of the command string that is - generated using a combination of the user’s Secret Key and the HMAC + generated using a combination of the User’s Secret Key and the HMAC SHA-1 hashing algorithm. .. parsed-literal:: @@ -194,7 +194,7 @@ To generate the signature. #. Take the sorted Command String and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method - to do this) with the user’s Secret Key. Base64 encode the resulting + to do this) with the User’s Secret Key. Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP. The final string produced after Base64 encoding should be "Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D". @@ -229,7 +229,7 @@ First import the required modules: Define the endpoint of the Cloud, the command that you want to execute -and the keys of the user. +and the keys of the User. .. parsed-literal:: @@ -431,7 +431,7 @@ results, the command will return 20 pages. The default page size limit can be different for each cloud. It is set in the global configuration parameter `default.page.size`. If your cloud -has many users with lots of VMs, you might need to increase the value of +has many users with lots of Instances, you might need to increase the value of this parameter. At the same time, be careful not to set it so high that your site can be taken down by an enormous return from an API call. For more information about how to set global configuration parameters, see @@ -555,7 +555,7 @@ is added to the new class named CSExceptionErrorCode. 4475 : "com.cloud.exception.InsufficientStorageCapacityException" -4480 : "com.cloud.exception.InsufficientVirtualNetworkCapcityException" +4480 : "com.cloud.exception.InsufficientVirtualNetworkCapacityException" 4485 : "com.cloud.exception.InternalErrorException" @@ -591,7 +591,7 @@ Asynchronous Commands Asynchronous commands were introduced in CloudStack 2.x. Commands are designated as asynchronous when they can potentially take a long period -of time to complete such as creating a snapshot or disk volume. They +of time to complete such as creating a Snapshot or disk volume. They differ from synchronous commands by the following: - They are identified in the API Reference by an (A). @@ -1134,7 +1134,7 @@ Event Types | | | | | TRAFFIC.TYPE.UPDATE | +-------------------+--------------------------------------------------------+ -| External network | PHYSICAL.LOADBALANCER.ADD | +| External Network | PHYSICAL.LOADBALANCER.ADD | | device events | | | | PHYSICAL.LOADBALANCER.DELETE | | | | @@ -1198,13 +1198,13 @@ Event Types | events | | | | DELETE\_RESOURCE\_DETAILS | +-------------------+--------------------------------------------------------+ -| VM snapshot | VMSNAPSHOT.CREATE | +| VM Snapshot | VMSNAPSHOT.CREATE | | events | | | | VMSNAPSHOT.DELETE | | | | | | VMSNAPSHOT.REVERTTO | +-------------------+--------------------------------------------------------+ -| External network | PHYSICAL.NVPCONTROLLER.ADD | +| External Network | PHYSICAL.NVPCONTROLLER.ADD | | device events | | | | PHYSICAL.NVPCONTROLLER.DELETE | | | | @@ -1292,7 +1292,7 @@ Time Zones The following time zone identifiers are accepted by CloudStack. There are several places that have a time zone as a required or optional -parameter. These include scheduling recurring snapshots, creating a +parameter. These include scheduling recurring Snapshots, creating a user, and specifying the usage time zone in the Configuration table. .. cssclass:: table-striped table-bordered table-hover diff --git a/source/developersguide/developer_guide.rst b/source/developersguide/developer_guide.rst index e4484b5b8f..9309c29c0f 100644 --- a/source/developersguide/developer_guide.rst +++ b/source/developersguide/developer_guide.rst @@ -18,26 +18,27 @@ CloudStack Installation from GIT repo for Developers ==================================================== This guide is aimed at CloudStack developers who need to build the code. -These instructions are valid on a Ubuntu 18.04 and CentOS 7 systems -and were tested with the 4.11 release of Apache CloudStack. Please -adapt them if you are on a different operating system or using a newer/older -version of CloudStack. This book is composed of the following sections: +These instructions are valid on a Ubuntu 22.04 and 24.04 systems +and were tested with the 4.19 release of Apache CloudStack. Community maintained +CloudStack self-learning course is also available at `CloudStack HackerBook +`__. + +Please adapt them if you are on a different operating system or using a +newer/older version of CloudStack. This book is composed of the following +sections: #. Installation of the prerequisites #. Compiling and installation from source -#. Using the CloudStack simulator +#. Using the CloudStack Simulator -#. Installation with DevCloud the CloudStack sandbox +#. Using Appliance for development #. Building your own packages #. The CloudStack API -#. Testing the AWS API interface - - Prerequisites ------------- @@ -49,27 +50,22 @@ installed: * jdk 11+ (openjdk-11-jdk) * maven 3+ * git -* python-pip -* python-setuptools +* python3-pip +* python3-setuptools * mkisofs -* A MySql Server +* MySql 8x Server -Example Ubuntu 18.04 -~~~~~~~~~~~~~~~~~~~~ +Example Ubuntu +~~~~~~~~~~~~~~ :: - apt update - apt install openjdk-11-jdk-headless maven git python-pip mkisofs git mysql-server + sudo apt update + sudo apt install git openssh-client openjdk-11-jdk maven mysql-client mysql-server nfs-kernel-server quota genisoimage python3 python3-pip -Example CentOS 7 -~~~~~~~~~~~~~~~~ - -:: - - yum install -y epel-release - yum localinstall -y http://dev.mysql.com/get/mysql-community-release-el7-5.noarch.rpm - yum install -y java-1.11.0-openjdk-devel maven python-setuptools python-pip genisoimage git mysql-community-server +Note: ensure to install python 3.8/3.9/3.10, as required you can install +specific Python3 versions using pyenv. Similarly, Java versions can be installed +and managed using jenv. Installing CloudStack from Source ---------------------------------- @@ -86,7 +82,14 @@ To build a stable release, checkout the branch for that version: :: - git checkout 4.11.2 + git checkout 4.19 + +Optional, you can install noredist/nonoss dependencies: + +:: + + git clone https://github.com/shapeblue/cloudstack-nonoss + cd cloudstack-nonoss && bash -x install-non-oss.sh To compile Apache CloudStack, go to the cloudstack source folder and run: @@ -96,7 +99,8 @@ run: mvn -Pdeveloper,systemvm clean install If you want to skip the tests add ``-DskipTests`` to the command above. -Do NOT use ``-Dmaven.test.skip=true`` because that will break the build. +Do NOT use ``-Dmaven.test.skip=true`` because that will break the build. To +build noredist/nonoss add ``-Dnoredist`` flag to the command. If you have set a root mysql password, you will need to adjust the password in ``utils/conf/db.properties`` @@ -113,13 +117,24 @@ Run Apache CloudStack with jetty for testing mvn -pl :cloud-client-ui jetty:run +To build and run the UI, do this: + +:: + + curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash - + sudo apt install nodejs + cd cloudstack/ui + npm install + npm run serve + Log Into Apache CloudStack: Open your Web browser and use this URL to connect to CloudStack: :: - http://localhost:8080/client/ + http://localhost:5050 # this runs the UI + http://localhost:8080/client/ # this is the API backend Replace ``localhost`` with the IP of your management server if need be. @@ -137,7 +152,7 @@ have to setup a physical infrastructure. Using the Simulator ------------------- -CloudStack comes with a simulator for hosts, VMs and network infrastructure, +CloudStack comes with a simulator for hosts, Instances and Network infrastructure, allowing you to use the CloudStack management server without using real servers. It also comes with Marvin, which can create a set of infrastructure based on a configuration file that defines the number @@ -168,122 +183,38 @@ Start jetty with the simulator enabled :: - mvn -Dsimulator -Dorg.eclipse.jetty.annotations.maxWait=120 -pl :cloud-client-ui jetty:run + mvn -Dsimulator -pl :cloud-client-ui jetty:run Setup a basic or advanced zone with Marvin. In a separate shell:// :: - python tools/marvin/marvin/deployDataCenter.py -i setup/dev/basic.cfg + python3 tools/marvin/marvin/deployDataCenter.py -i setup/dev/basic.cfg OR - python tools/marvin/marvin/deployDataCenter.py -i setup/dev/advanced.cfg + python3 tools/marvin/marvin/deployDataCenter.py -i setup/dev/advanced.cfg -At this stage log in the CloudStack management server at -http://localhost:8080/client with the credentials admin/password, you -should see a fully configured zone infrastructure. +At this stage log in the CloudStack management server UI at +http://localhost:5050 or using CLI with the API endpoint at +http://localhost:8080/client with the credentials admin/password, you should see +a fully configured zone infrastructure. You can now run integration tests, use the API etc. -Building non-free Packages --------------------------- - -Certain CloudStack packages are not built by default because they depend on -libraries without redistribution rights. To build these, you need to install -the dependencies manually. - -:: - - git clone https://github.com/rhtyd/cloudstack-nonoss - cd cloudstack-nonoss - ./install-non-oss.sh - -You can then build and run CloudStack as normal by adding the `-Dnodist` flag -to build and run lines, e.g. - -:: - - mvn -Dsimulator -Dnoredist -Dorg.eclipse.jetty.annotations.maxWait=120 -pl :cloud-client-ui jetty:run - -Using DevCloud --------------- +Using Appliance for development +------------------------------- The Installing from source section will only get you to the point of -runnign the management server, it does not get you any hypervisors. The -simulator section gets you a simulated datacenter for testing. With -DevCloud you can run at least one hypervisor and add it to your -management server the way you would a real physical machine. - -`DevCloud `__ -is the CloudStack sandbox, the standard version is a VirtualBox based -image. There is also a KVM based image for it. Here we only show steps -with the VirtualBox image. For KVM see the -`wiki `__. - -\*\* DevCloud Pre-requisites - -#. Install `VirtualBox `__ on your machine - -#. Run VirtualBox and under >Preferences create a *host-only interface* - on which you disable the DHCP server +running the management server, it does not get you any hypervisors. The +simulator section gets you a simulated datacenter for testing. An appliance +based development such as using ``mbx`` can allow you to run at least one +hypervisor and add it to your management server the way you would a real physical machine. -#. Download the DevCloud `image - `__ - -#. In VirtualBox, under File > Import Appliance import the DevCloud - image. - -#. Verify the settings under > Settings and check the ``enable PAE`` - option in the processor menu - -#. Once the VM has booted try to ``ssh`` to it with credentials: - ``root/password`` - - ssh root@192.168.56.10 - - -Adding DevCloud as an Hypervisor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Picking up from a clean build: - -:: - - mvn -Pdeveloper,systemvm clean install - mvn -P developer -pl developer,tools/devcloud -Ddeploydb - -At this stage install marvin similarly than with the simulator: - -:: - - pip install tools/marvin/dist/Marvin-|release|.tar.gz - -Start the management server - -:: - - mvn -pl client jetty:run - -Then you are going to configure CloudStack to use the running DevCloud -instance: - -:: - - cd tools/devcloud - python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg - -If you are curious, check the ``devcloud.cfg`` file and see how the data -center is defined: 1 Zone, 1 Pod, 1 Cluster, 1 Host, 1 primary Storage, -1 Seondary Storage, all provided by Devcloud. - -You can now log in the management server at -``http://localhost:8080/client`` and start experimenting with the UI or -the API. - -Do note that the management server is running in your local machine and -that DevCloud is used only as a n Hypervisor. You could potentially run -the management server within DevCloud as well, or memory granted, run -multiple DevClouds. +MonkeyBox or `mbx `__ +enable VM/appliance-based CloudStack development. It is tested with Ubuntu and +uses KVM and prebuilt images to deploy QA and dev environments for anybody to +try out CloudStack with a range of hypervisors, local and NFS storage. +Please refer to the project for more details: https://github.com/shapeblue/mbx Building Packages ----------------- @@ -320,7 +251,6 @@ One directory up from the CloudStack root dir you will find: cloudstack_|release|.dsc cloudstack_|release|.tar.gz cloudstack-agent_|release|_all.deb - cloudstack-awsapi_|release|_all.deb cloudstack-cli_|release|_all.deb cloudstack-common_|release|_all.deb cloudstack-docs_|release|_all.deb @@ -348,17 +278,17 @@ also developed that maps the GCE REST API to the CloudStack API described here. The API `docs `__ are a good start to learn the extent of the API. Multiple clients exist on -`github `__ +`GitHub `__ to use this API, you should be able to find one in your favorite language. The reference documentation for the API and changes that might -occur from version to version is availble +occur from version to version is available `on-line `__. This short section is aimed at providing a quick summary to give you a base understanding of how to use this API. As a quick start, a good way to explore the API is to navigate the dashboard with a firebug console (or similar developer console) to study the queries. -In a succint statement, the CloudStack query API can be used via http +In a succinct statement, the CloudStack query API can be used via http GET requests made against your cloud endpoint (e.g http://localhost:8080/client/api). The API name is passed using the ``command`` key and the various parameters for this API call are passed @@ -385,7 +315,7 @@ Open a Python shell and import the basic modules necessary to make the request. Do note that this request could be made many different ways, this is just a low level example. The ``urllib*`` modules are used to make the http request and do url encoding. The ``hashlib`` module gives -us the sha1 hash function. It used to geenrate the ``hmac`` (Keyed +us the sha1 hash function. It used to generate the ``hmac`` (Keyed Hashing for Message Authentication) using the secretkey. The result is encoded using the ``base64`` module. @@ -478,7 +408,7 @@ and the signature. Then do an http GET: } } -All the clients that you will find on github will implement this +All the clients that you will find on GitHub will implement this signature technique, you should not have to do it by hand. Now that you have explored the API through the UI and that you understand how to make low level calls, pick your favorite client of use @@ -487,53 +417,6 @@ is a sub-project of Apache CloudStack and gives operators/developers the ability to use any of the API methods. It has nice auto-completion and help feature as well as an API discovery mechanism since 4.2. - -Testing the AWS API interface ------------------------------ - -While the native CloudStack API is not a standard, CloudStack provides a -AWS EC2 compatible interface. It has the great advantage that existing -tools written with EC2 libraries can be re-used against a CloudStack -based cloud. In the installation books we described how to run this -interface from installing packages. In this section we show you how to -compile the interface with ``maven`` and test it with Python boto -module. - -Starting from a running management server (with DevCloud for instance), -start the AWS API interface in a separate shell with: - -:: - - mvn -Pawsapi -pl :cloud-awsapi jetty:run - -Log into the CloudStack UI ``http://localhost:8080/client``, go to -*Service Offerings* and edit one of the compute offerings to have the -name ``m1.small`` or any of the other AWS EC2 instance types. - -With access and secret keys generated for a user you should now be able -to use Python `Boto `__ module: - -:: - - import boto - import boto.ec2 - - accesskey="2IUSA5xylbsPSnBQFoWXKg3RvjHgsufcKhC1SeiCbeEc0obKwUlwJamB_gFmMJkFHYHTIafpUx0pHcfLvt-dzw" - secretkey="oxV5Dhhk5ufNowey7OVHgWxCBVS4deTl9qL0EqMthfPBuy3ScHPo2fifDxw1aXeL5cyH10hnLOKjyKphcXGeDA" - - region = boto.ec2.regioninfo.RegionInfo(name="ROOT", endpoint="localhost") - conn = boto.connect_ec2(aws_access_key_id=accesskey, aws_secret_access_key=secretkey, is_secure=False, region=region, port=7080, path="/awsapi", api_version="2012-08-15") - - images=conn.get_all_images() - print images - - res = images[0].run(instance_type='m1.small',security_groups=['default']) - -Note the new ``api_version`` number in the connection object and also -note that there was no user registration to make like in previous -CloudStack releases. - - Conclusions ----------- @@ -548,4 +431,4 @@ be. As a quick start, you might want to consider KVM+NFS and a Basic Zone. If you've run into any problems with this, please ask on the -cloudstack-dev `mailing list `__. +cloudstack-dev `mailing list `__. diff --git a/source/developersguide/get_help.rst b/source/developersguide/get_help.rst index 18466cbef0..9d9a2c2c88 100644 --- a/source/developersguide/get_help.rst +++ b/source/developersguide/get_help.rst @@ -27,6 +27,9 @@ Need some help getting started? Feel free to ask on the `mailing list discussions about development and the project itself happen. This is a high volume list. +Github users can also start discussion at +https://github.com/apache/cloudstack/discussions + Documentation Available ----------------------- @@ -35,7 +38,7 @@ The following guides are available: - CloudStack Concepts and Terminology - Quick Installation Guide - Installation Guide -- Upgradong CloudStack +- Upgrading CloudStack - Usage Guide - Developers Guide - Plugins Guide @@ -49,11 +52,15 @@ Books |60recipe| |acs-packt| |jp1| |jp2| -Commercial support ------------------- +Support +------- + +For community support you may ask on the project's users mailing list or via +Github discussions. Some companies offer commercial support for Apache CloudStack or their own -product based on CloudStack. +product based on CloudStack. You may ask on the list or `search yourself +`__. .. |60recipe| image:: /_static/images/60recipe.gif @@ -67,4 +74,4 @@ product based on CloudStack. :target: http://www.amazon.co.jp/gp/product/4798130583/ref=as_li_ss_tl?ie=UTF8&camp=247&creative=7399&creativeASIN=4798130583&linkCode=as2&tag=aaaaaaaeaeaea-22 .. |jp2| image:: /_static/images/jp2.jpg :alt: CloudStack実践ガイド[前編] - :target: http://www.amazon.co.jp/CloudStack%E5%AE%9F%E8%B7%B5%E3%82%AC%E3%82%A4%E3%83%89-%E5%89%8D%E7%B7%A8-NextPublishing-%E5%A4%A7%E5%89%8A-%E7%B7%91/dp/4844395920/ref=pd_bxgy_b_img_y \ No newline at end of file + :target: http://www.amazon.co.jp/CloudStack%E5%AE%9F%E8%B7%B5%E3%82%AC%E3%82%A4%E3%83%89-%E5%89%8D%E7%B7%A8-NextPublishing-%E5%A4%A7%E5%89%8A-%E7%B7%91/dp/4844395920/ref=pd_bxgy_b_img_y diff --git a/source/developersguide/index.rst b/source/developersguide/index.rst index 85ac8821c0..842f4732f0 100644 --- a/source/developersguide/index.rst +++ b/source/developersguide/index.rst @@ -24,7 +24,7 @@ Developers Guide ================ -This is the Apache CloudStack developers guide. This section gives information for those wishing to develop CloudStack either contributing to the CloudStack core software or writing external plugins. Futher information can also be found at CloudStack's wiki https://cwiki.apache.org/confluence/display/CLOUDSTACK/Home and on the CloudStack mailing lists http://cloudstack.apache.org/mailing-lists.html +This is the Apache CloudStack developers guide. This section gives information for those wishing to develop CloudStack either contributing to the CloudStack core software or writing external plugins. Further information can also be found at CloudStack's wiki https://cwiki.apache.org/confluence/display/CLOUDSTACK/Home and on the CloudStack mailing lists http://cloudstack.apache.org/mailing-lists.html .. toctree:: :maxdepth: 2 diff --git a/source/developersguide/plugins.rst b/source/developersguide/plugins.rst index 72d16ee798..ddb04814fe 100644 --- a/source/developersguide/plugins.rst +++ b/source/developersguide/plugins.rst @@ -39,14 +39,14 @@ available so that storage providers can develop vendor-specific plugins based on well-defined contracts that can be seamlessly managed by CloudStack. -Artifacts such as templates, ISOs and snapshots are kept in storage +Artifacts such as Templates, ISOs and Snapshots are kept in storage which CloudStack refers to as secondary storage. To improve scalability and performance, as when a number of hosts access secondary storage concurrently, object storage can be used for secondary storage. Object storage can also provide built-in high availability capability. When using object storage, access to secondary storage data can be made available across multiple zones in a region. This is a huge benefit, as -it is no longer necessary to copy templates, snapshots etc. across zones +it is no longer necessary to copy Templates, Snapshots etc. across zones as would be needed in an environment using only zone-based NFS storage. The user enables a storage plugin through the UI. A new dialog box @@ -70,7 +70,7 @@ steps (explained in more detail later in this section): - DataStoreProvider - - VMSnapshotStrategy (if you want to customize the VM snapshot + - VMSnapshotStrategy (if you want to customize the Instance Snapshot functionality) #. Hardcode your plugin's required additional input fields into the code @@ -167,7 +167,7 @@ VMSnapshotStrategy has the following methods: - revertVMSnapshot() -- canHandle(). For a given VM snapshot, tells whether this +- canHandle(). For a given Instance Snapshot, tells whether this implementation of VMSnapshotStrategy can handle it. @@ -339,385 +339,3 @@ http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/m | | Schedules a new transfer to upload data to Amazon S3. | +------------------+---------------------------------------------------------+ - -Third Party UI Plugins ----------------------- - -Using the new third-party plugin framework, you can write and install -extensions to CloudStack. The installed and enabled plugins will appear in -the UI alongside the other features. The code for the plugin is simply -placed in a special directory within CloudStack’s installed code at any -time after CloudStack installation. The new plugin appears only when it is -enabled by the cloud administrator. - -.. figure:: /_static/images/plugin_intro.png - :align: center - :alt: New plugin button in CloudStack navbar - -The left navigation bar of the CloudStack UI has a new Plugins button to -help you work with UI plugins. - - -How to Write a Plugin: Overview -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The basic procedure for writing a plugin is: - -#. Write the code and create the other files needed. You will need the - plugin code itself (in Javascript), a thumbnail image, the plugin - listing, and a CSS file. - - .. figure:: /_static/images/plugin1.jpg - :align: center - :alt: Write the plugin code - - All UI plugins have the following set of files: - - :: - - +-- cloudstack/ - +-- ui/ - +-- plugins/ - +-- csMyFirstPlugin/ - +-- config.js --> Plugin metadata (title, author, vendor URL, etc.) - +-- icon.png --> Icon, shown on side nav bar and plugin listing - (should be square, and ~50x50px) - +-- csMyFirstPlugin.css --> CSS file, loaded automatically when plugin loads - +-- csMyFirstPlugin.js --> Main JS file, containing plugin code - - - The same files must also be present at - `/tomcat/webapps/client/plugins`. - -#. The CloudStack administrator adds the folder containing your plugin code - under the CloudStack PLUGINS folder. - - .. figure:: /_static/images/plugin2.jpg - :align: center - :alt: The plugin code is placed in the PLUGINS folder - -#. The administrator also adds the name of your plugin to the plugin.js - file in the PLUGINS folder. - - .. figure:: /_static/images/plugin3.jpg - :align: center - :alt: The plugin name is added to `plugin.js` in the PLUGINS folder - -#. The next time the user refreshes the UI in the browser, your plugin - will appear in the left navigation bar. - - .. figure:: /_static/images/plugin4.png - :align: center - :alt: The plugin appears in the UI - - -How to Write a Plugin: Implementation Details -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section requires an understanding of JavaScript and the CloudStack -API. You don't need knowledge of specific frameworks for this tutorial -(jQuery, etc.), since the CloudStack UI handles the front-end rendering for -you. - -There is much more to the CloudStack UI framework than can be described -here. The UI is very flexible to handle many use cases, so there are -countless options and variations. The best reference right now is to -read the existing code for the main UI, which is in the /ui folder. -Plugins are written in a very similar way to the main UI. - -#. **Create the directory to hold your plugin.** - - All plugins are composed of set of required files in the directory - /ui/plugins/pluginID, where pluginID is a short name for your - plugin. It's recommended that you prefix your folder name (for - example, bfMyPlugin) to avoid naming conflicts with other people's - plugins. - - In this example, the plugin is named csMyFirstPlugin. - - :: - - $ cd cloudstack/ui/plugins - $ mkdir csMyFirstPlugin - $ ls -l - - total 8 - drwxr-xr-x 2 bgregory staff 68 Feb 11 14:44 csMyFirstPlugin - -rw-r--r-- 1 bgregory staff 101 Feb 11 14:26 plugins.js - -#. **Change to your new plugin directory.** - - :: - - $ cd csMyFirstPlugin - -#. **Set up the listing.** - - Add the file `config.js`, using your favorite editor. - - :: - - $ vi config.js - - Add the following content to config.js. This information will be - displayed on the plugin listing page in the UI: - - :: - - (function (cloudStack) { - cloudStack.plugins.csMyFirstPlugin.config = { - title: 'My first plugin', - desc: 'Tutorial plugin', - externalLink: 'http://www.cloudstack.org/', - authorName: 'Test Plugin Developer', - authorEmail: 'plugin.developer@example.com' - }; - }(cloudStack)); - - -#. **Add a new main section.** - - Add the file csMyFirstPlugin.js, using your favorite editor. - - :: - - $ vi csMyFirstPlugin.js - - Add the following content to csMyFirstPlugin.js: - - :: - - (function (cloudStack) { - cloudStack.plugins.csMyFirstPlugin = function(plugin) { - plugin.ui.addSection({ - id: 'csMyFirstPlugin', - title: 'My Plugin', - preFilter: function(args) { - return isAdmin(); - }, - show: function() { - return $('
').html('Content will go here'); - } - }); - }; - }(cloudStack)); - - -#. **Register the plugin.** - - You now have the minimal content needed to run the plugin, so you - can activate the plugin in the UI by adding it to plugins.js. First, - edit the file: - - :: - - $ cd cloudstack/ui/plugins - $ vi plugins.js - - - Now add the following to plugins.js: - - :: - - (function($, cloudStack) { - cloudStack.plugins = [ - 'csMyFirstPlugin' - ]; - }(jQuery, cloudStack)); - - -#. **Check the plugin in the UI.** - - First, copy all the plugin code that you have created so far to - `/tomcat/webapps/client/plugins`. Then refresh the browser and click - Plugins in the side navigation bar. You should see your new plugin. - -#. **Make the plugin do something.** - - Right now, you just have placeholder content in the new plugin. It's - time to add real code. In this example, you will write a basic list - view, which renders data from an API call. You will list all virtual - machines owned by the logged-in user. To do this, replace the 'show' - function in the plugin code with a 'listView' block, containing the - required syntax for a list view. To get the data, use the - listVirtualMachines API call. Without any parameters, it will return - VMs only for your active user. Use the provided 'apiCall' helper - method to handle the server call. Of course, you are free to use any - other method for making the AJAX call (for example, jQuery's $.ajax - method). - - First, open your plugin's JavaScript source file in your favorite - editor: - - :: - - $ cd csMyFirstPlugin - $ vi csMyFirstPlugin.js - - - Add the following code in csMyFirstPlugin.js: - - :: - - (function (cloudStack) { - cloudStack.plugins.csMyFirstPlugin = function(plugin) { - plugin.ui.addSection({ - id: 'csMyFirstPlugin', - title: 'My Plugin', - preFilter: function(args) { - return isAdmin(); - }, - - // Render page as a list view - listView: { - id: 'testPluginInstances', - fields: { - name: { label: 'label.name' }, - instancename: { label: 'label.internal.name' }, - displayname: { label: 'label.display.name' }, - zonename: { label: 'label.zone.name' } - }, - dataProvider: function(args) { - // API calls go here, to retrive the data asynchronously - // - // On successful retrieval, call - // args.response.success({ data: [data array] }); - plugin.ui.apiCall('listVirtualMachines', { - success: function(json) { - var vms = json.listvirtualmachinesresponse.virtualmachine; - - args.response.success({ data: vms }); - }, - error: function(errorMessage) { - args.response.error(errorMessage) - } - }); - } - } - }); - }; - }(cloudStack)); - - -#. **Test the plugin.** - - First, copy all the plugin code that you have created so far to - `/tomcat/webapps/client/plugins`. Then refresh the browser. You can - see that your placeholder content was replaced with a list table, - containing 4 columns of virtual machine data. - -#. **Add an action button.** - - Let's add an action button to the list view, which will reboot the - VM. To do this, add an actions block under listView. After - specifying the correct format, the actions will appear automatically - to the right of each row of data. - - :: - - $ vi csMyFirstPlugin.js - - - Now add the following new code in csMyFirstPlugin.js. (The dots ... - show where we have omitted some existing code for the sake of space. - Don't actually cut and paste that part): - - :: - - ... - listView: { - id: 'testPluginInstances', - ... - - actions: { - // The key/ID you specify here will determine what icon is - // shown in the UI for this action, - // and will be added as a CSS class to the action's element - // (i.e., '.action.restart') - // - // -- here, 'restart' is a predefined name in CloudStack that will - // automatically show a 'reboot' arrow as an icon; - // this can be changed in csMyFirstPlugin.css - restart: { - label: 'Restart VM', - messages: { - confirm: function() { return 'Are you sure you want to restart this VM?' }, - notification: function() { return 'Rebooted VM' } - }, - action: function(args) { - // Get the instance object of the selected row from context - // - // -- all currently loaded state is stored in 'context' as objects, - // such as the selected list view row, - // the selected section, and active user - // - // -- for list view actions, the object's key will be the same as - // listView.id, specified above; - // always make sure you specify an 'id' for the listView, - // or else it will be 'undefined!' - var instance = args.context.testPluginInstances[0]; - - plugin.ui.apiCall('rebootVirtualMachine', { - // These will be appended to the API request - // - // i.e., rebootVirtualMachine&id=... - data: { - id: instance.id - }, - success: function(json) { - args.response.success({ - // This is an async job, so success here only indicates - // that the job was initiated. - // - // To pass the job ID to the notification UI - // (for checking to see when action is completed), - // '_custom: { jobID: ... }' needs to always be passed on success, - // in the same format as below - _custom: { jobId: json.rebootvirtualmachineresponse.jobid } - }); - }, - - - error: function(errorMessage) { - args.response.error(errorMessage); // Cancel action, show error message returned - } - }); - }, - - // Because rebootVirtualMachine is an async job, we need to add - // a poll function, which will perodically check - // the management server to see if the job is ready - // (via pollAsyncJobResult API call) - // - // The plugin API provides a helper function, 'plugin.ui.pollAsyncJob', - / which will work for most jobs - // in CloudStack - notification: { - poll: plugin.ui.pollAsyncJob - } - } - }, - - dataProvider: function(args) { - ... - ... - - -#. **Add the thumbnail icon.** - - Create an icon file; it should be square, about 50x50 pixels, and - named `icon.png`. Copy it into the same directory with your plugin - code: `cloudstack/ui/plugins/csMyFirstPlugin/icon.png`. - -#. **Add the stylesheet.** - - Create a CSS file, with the same name as your `.js` file. Copy it into - the same directory with your plugin code: - `cloudstack/ui/plugins/csMyFirstPlugin/csMyFirstPlugin.css`. - - -.. | plugin_intro.png: New plugin button in CloudStack navbar | image:: _static/images/plugin_intro.png -.. | plugin1.jpg: Write the plugin code | image:: _static/images/plugin1.jpg -.. | plugin2.jpg: The plugin code is placed in the PLUGINS folder | image:: _static/images/plugin2.jpg -.. | plugin3.jpg: The plugin name is added to plugin.js in the PLUGINS folder | image:: _static/images/plugin3.jpg -.. | plugin4.png: The plugin appears in the UI | image:: _static/images/plugin4.png diff --git a/source/index.rst b/source/index.rst index fc0fb47ecf..b9b369e0a4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -51,15 +51,9 @@ Information can also be found at CloudStack's wiki https://cwiki.apache.org/conf Apache CloudStack web site Apache CloudStack Source Code Apache CloudStack on GitHub + Apache CloudStack Documentation on GitHub -.. toctree:: - :caption: Pre 4.11 Documentation: - - Installation Guide - Administration Guide - Release Notes - Indices and Tables ================== diff --git a/source/installguide/building_from_source.rst b/source/installguide/building_from_source.rst index 94da1d0a6b..0708418ee8 100644 --- a/source/installguide/building_from_source.rst +++ b/source/installguide/building_from_source.rst @@ -267,7 +267,7 @@ several other dependencies. Note that we recommend using Maven 3. While we have defined, and you have presumably already installed the bootstrap prerequisites, there are a number of build time prerequisites that need to be resolved. CloudStack uses maven for dependency -resolution. You can resolve the buildtime depdencies for CloudStack by +resolution. You can resolve the buildtime dependencies for CloudStack by running: .. parsed-literal:: @@ -483,9 +483,9 @@ Generating RPMs is done using the ``package.sh`` script: .. parsed-literal:: - $ ./package.sh -d centos63 + $ ./package.sh -d el8 -For other supported options(like centos7), run ``./package.sh --help`` +For other supported options, run ``./package.sh --help`` That will run for a bit and then place the finished packages in ``dist/rpmbuild/RPMS/x86_64/``. @@ -505,7 +505,7 @@ Creating a yum repo ^^^^^^^^^^^^^^^^^^^ While RPMs is a useful packaging format - it's most easily consumed from -Yum repositories over a network. The next step is to create a Yum Repo +Yum repositories over a Network. The next step is to create a Yum Repo with the finished packages: .. parsed-literal:: @@ -537,7 +537,7 @@ named ``/etc/yum.repos.d/cloudstack.repo`` with this information: gpgcheck=0 Completing this step will allow you to easily install CloudStack on a -number of machines across the network. +number of machines across the Network. .. _building-noredist: @@ -568,7 +568,7 @@ to build from source. page on the wiki. #. You may also need to download - `vhd-util `_, + `vhd-util `_, which was removed due to licensing issues. You'll copy vhd-util to the ``scripts/vm/hypervisor/xenserver/`` directory. diff --git a/source/installguide/configuration.rst b/source/installguide/configuration.rst index 402e70a456..bdfbb77a02 100644 --- a/source/installguide/configuration.rst +++ b/source/installguide/configuration.rst @@ -47,6 +47,8 @@ follow these procedures: #. Add secondary storage to the zone. See :ref:`add-secondary-storage`. +#. Register Templates to the zone. See :ref:`register-templates`. + #. Initialize and test the new cloud. See :ref:`initialize-and-test`. When you have finished these steps, you will have a deployment with the @@ -264,10 +266,16 @@ and secondary storage. #. Click Add Zone. The zone creation wizard will appear. -#. Choose one of the following network types: +#. Choose one of the following zone types: + + - **Core.** Core Zones are intended for Datacenter based deployments and allow the full range of Networking and other functionality in Apache CloudStack. Core zones have a number of prerequisites and rely on the presence of shared storage and helper Instances. For more information see :ref:`core-zone`. + + - **Edge.** Edge Zones are lightweight zones, designed for deploying in edge computing scenarios. They are limited in functionality but have far fewer prerequisites than core zones. Please refer to :ref:`edge-zone`. + +#. If Core Zone is selected, choose one of the following network types: - **Basic.** For AWS-style networking. Provides a single network - where each VM instance is assigned an IP directly from the + where each instance is assigned an IP directly from the network. Guest isolation can be provided through layer-3 means such as security groups (IP address source filtering). @@ -277,7 +285,7 @@ and secondary storage. VPN, or load balancer support. - **Security Groups.** You can choose to enable Security Groups in your zone. - For further informations regarding Security Groups and there prequesits + For further information regarding Security Groups and there prequesits please refer to the Security Groups section in the documentation. #. The rest of the steps differ depending on whether you chose Basic or @@ -287,6 +295,9 @@ and secondary storage. - `“Advanced Zone Configuration” <#advanced-zone-configuration>`_ +.. note:: + Since CloudStack 4.20.1, it is possible to specify the preferred architecture type for a zone for deployment of system VM including virtual routers. Zone setting - *system.vm.preferred.architecture* can be updated for this. The server will first try deployment on the preferred architecture and if it fails then will attempt on other architecture hosts. + Administrator can also register ROUTING template with the same name for different architectures to allow deployment across them depending on the compute capacity. For other system VMs, server will attempt deployment using different architecture templates available. Basic Zone Configuration ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -296,13 +307,13 @@ Basic Zone Configuration - **Name.** A name for the zone. - - **DNS 1 and 2.** These are DNS servers for use by guest VMs in the + - **DNS 1 and 2.** These are DNS servers for use by Guest Instances in the zone. These DNS servers will be accessed via the public network you will add later. The public IP addresses for the zone must have a route to the DNS server named here. - **Internal DNS 1 and Internal DNS 2.** These are DNS servers for - use by system VMs in the zone (these are VMs used by CloudStack + use by system VMs in the zone (these are instances used by CloudStack itself, such as virtual routers, console proxies, and Secondary Storage VMs.) These DNS servers will be accessed via the management traffic network interface of the System VMs. The @@ -315,25 +326,25 @@ Basic Zone Configuration zone. - **Network Offering.** Your choice here determines what network - services will be available on the network for guest VMs. + services will be available on the network for Guest Instances. .. cssclass:: table-striped table-bordered table-hover =============================================== =================================================================================================================== Network Offering Description =============================================== =================================================================================================================== - DefaultSharedNetworkOfferingWithSGService If you want to enable security groups for guest traffic isolation, choose this. (See Using Security Groups to Control Traffic to VMs.) + DefaultSharedNetworkOfferingWithSGService If you want to enable security groups for guest traffic isolation, choose this. (See Using Security Groups to Control Traffic to instances.) DefaultSharedNetworkOffering If you do not need security groups, choose this. DefaultSharedNetscalerEIPandELBNetworkOffering If you have installed a Citrix NetScaler appliance as part of your zone network, and you will be using its Elastic IP and Elastic Load Balancing features, choose this. With the EIP and ELB features, a basic zone with security groups enabled can offer 1:1 static NAT and load balancing. =============================================== =================================================================================================================== - **Network Domain.** (Optional) If you want to assign a special - domain name to the guest VM network, specify the DNS suffix. + domain name to the Guest Instance network, specify the DNS suffix. - **Public.** A public zone is available to all users. A zone that is not public will be assigned to a particular domain. Only users - in that domain will be allowed to create guest VMs in this zone. + in that domain will be allowed to create Guest Instances in this zone. #. Choose which traffic types will be carried by the physical network. @@ -402,11 +413,14 @@ Basic Zone Configuration - **Start IP/End IP.** A range of IP addresses that are assumed to be accessible from the Internet and will be allocated for access - to guest VMs. + to Guest Instances. #. In a new zone, CloudStack adds the first pod for you. You can always add more pods later. For an overview of what a pod is, see :ref:`about-pods` +.. note:: + The network described below must be a subnet of the physical network marked as type "management". + To configure the first pod, enter the following, then click Next: - **Pod Name.** A name for the pod. @@ -462,7 +476,7 @@ Basic Zone Configuration .. note:: When you add a hypervisor host to CloudStack, the host must not have - any VMs already running. + any instances already running. Before you can configure the host, you need to install the hypervisor software on the host. You will need to know which version of the @@ -485,12 +499,25 @@ Basic Zone Configuration - **Password.** This is the password for the user named above (from your XenServer or KVM install). + One additional facility that is available in case of KVM is, host can also be added + using CloudStack's SSH key without having to provide host password. + + Before adding the host in CloudStack do the following, + + - Copy the SSH public key from /var/cloudstack/management/.ssh/id_rsa.pub on the management server + - Add the copied key to /root/.ssh/authorized_keys file on the host + + .. TIP:: + On Ubuntu systems, the key will be in ``/var/lib/cloudstack/management/.ssh/id_rsa.pub`` instead. + + Select "System SSH Key" and proceed with next steps. + - **Host Tags.** (Optional) Any labels that you use to categorize hosts for ease of maintenance. For example, you can set this to the cloud's HA tag (set in the ha.tag global configuration - parameter) if you want this host to be used only for VMs with the + parameter) if you want this host to be used only for instances with the "high availability" feature enabled. For more information, see - HA-Enabled Virtual Machines as well as HA for Hosts. + HA-Enabled Instances as well as HA for Hosts. #. In a new cluster, CloudStack adds the first primary storage server for you. You can always add more servers later. For an overview of @@ -502,7 +529,7 @@ Basic Zone Configuration - **Name.** The name of the storage device. - **Protocol.** For XenServer, choose either NFS, iSCSI, or - PreSetup. For KVM, choose NFS, SharedMountPoint,CLVM, RBD or custom (for PowerFlex). For + PreSetup. For KVM, choose NFS, SharedMountPoint,CLVM, RBD, FiberChannel or custom (for PowerFlex). For vSphere choose either VMFS (iSCSI or FiberChannel) or NFS. The remaining fields in the screen vary depending on what you choose here. @@ -511,41 +538,47 @@ Basic Zone Configuration Advanced Zone Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. After you select Advanced in the Add Zone wizard and click Next, you - will be asked to enter the following details. Then click Next. +For Advanced zone, you may chose to select Edge which will allow creating an Edge Zone. If Edge is not selected then wizard will continue creating a Core zone. + +.. _core-zone: + +Core Zone +********* + +#. For a Core zone, you will be asked to enter the following details. Then click Next. - **Name.** A name for the zone. - - **DNS 1 and 2.** (DNS 1 obligatory)These are DNS servers for use by guest VMs in the + - **DNS 1 and 2.** (DNS 1 obligatory)These are DNS servers for use by Guest Instances in the zone. These DNS servers will be accessed via the public network you will add later. The public IP addresses for the zone must have a route to the DNS server named here. - **Internal DNS 1 and Internal DNS 2.** (DNS 1 obligatory) - These are DNS servers for use by system VMs in the zone(these are - VMs used by CloudStack itself, such as virtual routers, console + These are DNS servers for use by system VMs in the zone(these are + instances used by CloudStack itself, such as virtual routers, console proxies,and Secondary Storage VMs.) These DNS servers will be accessed via the management traffic network interface of the System VMs. The private IP address you provide for the pods must have a route to the internal DNS server named here. - **Network Domain.** If you want to assign a special - domain name to the guest VM network, specify the DNS suffix. + domain name to the Guest Instance network, specify the DNS suffix. - **Hypervisor.** (Obligatory) Choose the hypervisor for the first cluster in the zone. You can add clusters with different hypervisors later, after you finish adding the zone. - - **Dedicated.** A dedicated zone is available to selected users or groups - within a domain. Only specified users or grous in that domain will - be allowed to create guest VMs in this zone. + - **Dedicated.** A dedicated zone is available to selected users or groups + within a domain. Only specified users or groups in that domain will + be allowed to create Guest Instances in this zone. - - **Enable local storage for User VMs.** Give the user the opperunity to - provide local storage (physical storage on the host) for User VMs to store data. + - **Enable local storage for User instances.** Give the user the opportunity to + provide local storage (physical storage on the host) for User instances to store data. - - **Enable local storage for System VMs.** Give the system the opperunity to + - **Enable local storage for System VMs.** Give the system the opportunity to use local storage (physical storage on the hosts) for System VMs. - + #. Click Next. #. Choose which traffic types will be carried by the physical network. @@ -588,6 +621,9 @@ Advanced Zone Configuration #. In a new zone, CloudStack adds the first pod for you. You can always add more pods later. For an overview of what a pod is, see :ref:`about-pods` +.. note:: + The network described below must be a subnet of the physical network marked as type "management". + To configure the first pod, enter the following, then click Next: - **Pod Name.** (Obligatory) A name for the pod. @@ -598,13 +634,13 @@ Advanced Zone Configuration - **Reserved system netmask.** (Obligatory) The network prefix that defines the pod's subnet. Use CIDR notation. - - **Start/End Reserved System IP.** (Start Reserved System IP - obligatory) - The IP range in the management network that CloudStack uses to manage + - **Start/End Reserved System IP.** (Start Reserved System IP - obligatory) + The IP range in the management network that CloudStack uses to manage various system VMs, such as Secondary Storage VMs, Console Proxy VMs, and DHCP. For more information, see :ref:`about_system_reserved_ip_addresses` -#. Configure the IP range for guest traffic. Guest network traffic is - communication between end-user virtual machines. Enter the +#. Configure the IP range for guest traffic. Guest network traffic is + communication between end-user Instances. Enter the following details, then click Add. When done, click Next. - **Guest Gateway.** The gateway in use for these IP addresses. @@ -617,6 +653,8 @@ Advanced Zone Configuration - **VLAN / VNI ID.** The VLAN / VNI ID's that will be used for guest traffic. +.. note:: If the VNI is of a VXLAN, the protocol prefix `vxlan://` must be used, like in `vxlan://` + #. In a new pod, CloudStack adds the first cluster for you. You can always add more clusters later. For an overview of what a cluster is, see :ref:`about-clusters` @@ -630,7 +668,7 @@ Advanced Zone Configuration always add more hosts later. For an overview of what a host is, see :ref:`about-hosts`. .. note:: - When you deploy CloudStack, the hypervisor host must not have any VMs + When you deploy CloudStack, the hypervisor host must not have any instances already running. Before you can configure the host, you need to install the hypervisor @@ -649,22 +687,22 @@ Advanced Zone Configuration - **Host Name.** (Obligatory) The DNS name or IP address of the host. - - **Username.** (Obligatory) Username of a user who has administrator / root privilidges on + - **Username.** (Obligatory) Username of a user who has administrator / root privileges on the specified host (using Linux-hosts usually root). - **Password.** (Obligatory) This is the password for the user named above (from your XenServer or KVM install). .. note:: - For security reasons there are ways to use non-adminstrative users for - adding a host. Please refer to the hypervisor setup guides for further information. + For security reasons there are ways to use non-administrative users for + adding a host. Please refer to the hypervisor setup guides for further information. - **Host Tags.** Any labels that you use to categorize hosts for ease of maintenance. For example, you can set to the cloud's HA tag (set in the ha.tag global configuration parameter) - if you want this host to be used only for VMs with the "high + if you want this host to be used only for instances with the "high availability" feature enabled. For more information, see - HA-Enabled Virtual Machines as well as HA for Hosts, both in the + HA-Enabled Instances as well as HA for Hosts, both in the Administration Guide. #. In a new cluster, CloudStack adds the first primary storage server @@ -744,7 +782,7 @@ Advanced Zone Configuration Before you can fill out this screen, you need to prepare the secondary storage by setting up NFS shares and installing the latest - CloudStack System VM template. See Adding Secondary Storage : + CloudStack System VM Template. See Adding Secondary Storage : - **NFS Server.** The IP address of the server or fully qualified domain name of the server. @@ -754,6 +792,58 @@ Advanced Zone Configuration #. Click Launch. +.. _edge-zone: + +Edge Zone +********* + +.. note:: + Support for Edge zones has been added with 4.18.0 and these zones will only be supported on KVM hypervisors + +An Edge Zone is a simpler, light-weight zone which may often contain a single hypervisor host. There will be no need for shared storage, public and management physical networks for an Edge zone. +To work with limited compute resources, an Edge zone will not deploy system VMs. This type of zone only supports shared and L2 guest networks. For virtual routers of a shared guest network, a direct-download System VM must be added after adding the zone. + +#. For an Edge zone, you will be asked to enter the following details + + - **Name.** A name for the zone. + + - **Hypervisor.** (Obligatory) Choose the hypervisor for the zone. Currently, this is disabled and set to KVM. + + - **Dedicated.** A dedicated zone is available to selected users or groups within a domain. Only specified users or groups in that domain will be allowed to create Guest Instances in this zone. + +#. Click Next. + +#. Choose the details for the physical network that will carry guest. + +#. Click Next. + +#. Specify VLAN/VNI range for guest traffic isolation. + +#. Click Next. + +#. Configure the host for the zone, enter the following, then click Next: + + - **Host Name.** (Obligatory) The DNS name or IP address of the host. + + - **Username.** (Obligatory) Username of a user who has administrator / root privileges on the specified host (using Linux-hosts usually root). + + - **Authentication.** Authentication type used for the host, either Password or System SSH Key. + + - **Password.** (Obligatory if Password authentication is selected) This is the password for the user named above. + + .. note:: + For security reasons there are ways to use non-administrative users for + adding a host. Please refer to the hypervisor setup guides for further information. + + - **Host Tags.** Any labels that you use to categorize + hosts for ease of maintenance. For example, you can set to the + cloud's HA tag (set in the ha.tag global configuration parameter) + if you want this host to be used only for instances with the "high + availability" feature enabled. For more information, see + HA-Enabled Instances as well as HA for Hosts, both in the + Administration Guide. + + .. _adding-a-pod: Adding a Pod @@ -786,6 +876,9 @@ can add more pods at any time using the procedure in this section. Secondary Storage VMs, Console Proxy VMs, and DHCP. For more information, see System Reserved IP Addresses. +.. note:: + * The network described above must be a subnet of the management network. + #. Click OK. @@ -798,6 +891,9 @@ You need to tell CloudStack about the hosts that it will manage. Hosts exist inside clusters, so before you begin adding hosts to the cloud, you must add at least one cluster. +.. note:: + Since CloudStack 4.20.0, it is possible to specify the hosts arch type which must be homogeneous within the cluster. AMD 64 bits (x86_64) and ARM 64 bits (aarch64) arch types are supported. The pre-existing clusters are set to arch type AMD 64 bits as well as new clusters in which the arch type is not specified. + Add Cluster: KVM or XenServer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -816,6 +912,8 @@ hosts and logged in to the CloudStack UI. #. Choose the hypervisor type for this cluster. +#. Choose the arch type of the hosts within the cluster. + #. Choose the pod in which you want to create the cluster. #. Enter a name for the cluster. This can be text of your choosing and @@ -841,7 +939,7 @@ requirements: - Do not put more than 8 hosts in a vSphere cluster -- Make sure the hypervisor hosts do not have any VMs already running +- Make sure the hypervisor hosts do not have any instances already running before you add them to CloudStack. To add a vSphere cluster to CloudStack: @@ -896,7 +994,7 @@ Adding a Host #. Before adding a host to the CloudStack configuration, you must first install your chosen hypervisor on the host. CloudStack can manage - hosts running VMs under a variety of hypervisors. + hosts running instances under a variety of hypervisors. The CloudStack Installation Guide provides instructions on how to install each supported hypervisor and configure it for use with @@ -927,15 +1025,15 @@ XenServer and KVM hosts can be added to a cluster at any time. Requirements for XenServer and KVM Hosts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**************************************** .. warning:: - Make sure the hypervisor host does not have any VMs already running before + Make sure the hypervisor host does not have any instances already running before you add it to CloudStack. Configuration requirements: -- Each cluster must contain only hosts with the identical hypervisor. +- Each cluster must contain only hosts with the identical hypervisor and arch type. - For XenServer, do not put more than 8 hosts in a cluster. @@ -944,9 +1042,11 @@ Configuration requirements: For hardware requirements, see the installation section for your hypervisor in the CloudStack Installation Guide. +.. note:: + Since CloudStack 4.20.0, the host arch type is auto detected when adding the host into CloudStack and it must match the cluster arch type for the operation to succeed. XenServer Host Additional Requirements -'''''''''''''''''''''''''''''''''''''' +************************************** If network bonding is in use, the administrator must cable the new host identically to other hosts in the cluster. @@ -980,7 +1080,7 @@ bonds on the new hosts in the cluster. KVM Host Additional Requirements -'''''''''''''''''''''''''''''''' +******************************** - If shared mountpoint storage is in use, the administrator should ensure that the new host has all the same mountpoints (with storage @@ -1001,8 +1101,8 @@ KVM Host Additional Requirements cloudstack ALL=NOPASSWD: /usr/bin/cloudstack-setup-agent defaults:cloudstack !requiretty -Adding a XenServer or KVM Host -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Adding a XenServer Host +*********************** #. If you have not already done so, install the hypervisor software on the host. You will need to know which version of the hypervisor @@ -1030,15 +1130,14 @@ Adding a XenServer or KVM Host - Username. Usually root. - - Password. This is the password for the user from your XenServer or - KVM install). + - Password. This is the password for the user from your XenServer install). - Host Tags (Optional). Any labels that you use to categorize hosts for ease of maintenance. For example, you can set to the cloud's HA tag (set in the ha.tag global configuration parameter) if you want this host to be used only for VMs with the "high availability" feature enabled. For more information, see - HA-Enabled Virtual Machines as well as HA for Hosts. + HA-Enabled Instances as well as HA for Hosts. There may be a slight delay while the host is provisioned. It should automatically display in the UI. @@ -1046,6 +1145,23 @@ Adding a XenServer or KVM Host #. Repeat for additional hosts. +Adding a KVM Host +***************** + +The steps to add a KVM host are same as adding a XenServer Host as mentioned in +the above section. +One additional facility that is available in case of KVM is, host can also be added +using CloudStack's SSH key without having to provide host password. + +Before adding the host in CloudStack do the following, + + - Copy the SSH public key from /var/cloudstack/management/.ssh/id_rsa.pub on the management server + - Add the copied key to /root/.ssh/authorized_keys file on the host + +While adding the host from CloudStack UI, select "System SSH Key" as shown below + + |add-Host.png: Adding a KVM Host| + .. _adding-a-host-vsphere: Adding a Host (vSphere) @@ -1081,7 +1197,7 @@ When setting up primary storage, follow these restrictions: - If you do not provision shared primary storage, you must set the global configuration parameter system.vm.local.storage.required to - true, or else you will not be able to start VMs. + true, or else you will not be able to start instances. Adding Primary Storage @@ -1221,7 +1337,7 @@ ever one) CloudStack volume, so performance of the CloudStack volume does not vary depending on how heavily other tenants are using the system. -The createStoragePool API has been augmented to support plugable storage +The createStoragePool API has been augmented to support pluggable storage providers. The following is a list of parameters to use when adding storage to CloudStack that is based on the SolidFire plug-in: @@ -1293,7 +1409,7 @@ so performance of the CloudStack volume does not vary depending on how heavily o tenants are using the system. This volume migration is supported across PowerFlex storage pools only, which are on same or distinct storage instance. -The createStoragePool API has been augmented to support plugable storage +The createStoragePool API has been augmented to support pluggable storage providers. The following is a list of parameters to use when adding storage to CloudStack that is based on the PowerFlex plug-in: @@ -1315,7 +1431,7 @@ storage to CloudStack that is based on the PowerFlex plug-in: - url=[storage pool url] -The url parameter contains the PowerFlex storage pool details, specifed +The url parameter contains the PowerFlex storage pool details, specified in the following format: powerflex://:@/ @@ -1328,6 +1444,155 @@ powerflex://:@/ - =[PowerFlex storage pool name (case sensitive)] +StorPool Plug-in +~~~~~~~~~~~~~~~~ + +.. note:: + The StorPool storage plug-in for CloudStack described here is part of + the standard installation for CloudStack versions 4.17.0.0 and newer. + There is no additional work required to add this component. + + In case you use a version before 4.17.0.0, you should install the + StorPool plug-in provided in the `StorPool CloudStack + `_ + repository. + +The StorPool plug-in is deeply integrated with CloudStack and works with KVM +hypervisors. For more information on how you can accelerate your CloudStack +deployment using CloudStack and StorPool together, see the `StorPool +`_ site. + +When used with service or disk offerings, an administrator is able to +build an environment in which a root or data disk that a user creates +leads to the dynamic creation of a StorPool volume, which has guaranteed +performance. Such a StorPool volume is associated with one CloudStack volume, +so performance of the CloudStack volume does not vary depending on how +heavily other tenants are using the system. The volume migration is supported +across non-managed storage pools (e.g. NFS/Local storage/Ceph) to StorPool, and +across StorPool storage pools. + +For detailed information about *Command*, *Scope*, *Hypervisor*, and other +parameters you need to specify when setting up the StorPool plug-in, see the +`CloudStack integration +`_ +documentation. + +HPE Primera/3PAR Plug-in +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This plugin enables Hewlett Packard Enterprise (HPE) Primera (previously 3PAR) storage systems with FiberChannel on KVM hypervisors. + +This documentation assumes you have the following configured in your environment before configuring a storage pool in cloudstack: + +- Deployed an HPE Primera storage system deployment supporting the HPE Web Services API v1.10+ (https://support.hpe.com/hpesc/public/docDisplay?docId=a00118636en_us&page=index.html) +- FiberChannel fabric and connectivity to every KVM host where volumes be attached to virtual machines. +- Host definitions in the Primera Array that match the name of the hostwill in CloudStack. This can be fully-qualified or just the hostname. +- Hostset defined to match the group of hosts associated with the Cloudstack cluster. +- Username and password to access the API with at least Edit privileges. +- CPG (Common Provisioning Group) defined in the HPE Primera storage system where volumes and snapshots can be provisioned. + +When this storage pool is used with Compute or Disk Offerings, an administrator is +able to build an environment in which a root or data disk that a user creates leads +to the dynamic creation of a Virtual Volume in an HPE Primera storage system. +Such a virtual volume is associated with one (and only ever one) CloudStack volume, +so performance of the CloudStack volume does not vary depending on how heavily other +tenants are using the system. Volume migration is supported between different +HPE Primera Storage provider implementations, between HPE Primera Storage Pools and +NFS Storage Pools, and between other providers that support cross-provider volume migration. + +The createStoragePool API can be used to configure an HPE Primera storage pool with the +following parameters: + +- command=createStoragePool +- scope=[zone | cluster]. Note this must match your Hostset configuration (below) +- zoneid=[your zone id] +- podid=[your pod id, for cluster-wide primary storage] +- clusterid=[your cluster id, for cluster-wide primary storage] +- name=[name for primary storage] +- hypervisor=KVM +- provider=Primera +- capacitybytes=The total capacity bytes available to the pool (before overprovisioning configuration is applied). If provided, this must be less than the total available capacity of the CPG on the storage system. If its not provided, defaults to the CPG maximum space. +- url=[url to storage system] + +The url parameter contains the HPE Primera storage pool details, specified +in the following format: + +https://:@:/api/v1?cpg=&hostset=&api_skiptlsvalidation=" + +- API_USER: user name for API access to HPE Primera. This can also be configured with "details[0].api_username" in the createStoragePool API call. +- API_PASSWORD: password for API access to HPE Primera (password is URL encoded for example, '=' is represented as '%3D'). This can also be configured with "details[0].api_password" in the createStoragePool API call. +- STORAGEIPORHOST: hostname and IP address for API access to HPE Primera +- STORAGEPORT: port for API access to HPE Primera +- HOSTSETNAME: name of the hostset in HPE Primera containing the hosts the cluster or zone has access to +- api_skiptlsvalidation: disable TLS certificate validation for HPE Primera API access + +When a volume is created by the plugin, it will create bi-directional mappings in Cloudstack and the storage system: + +- Because of storage system volume name length constraints, the storage system volume name will be a formatted string formatted as: "----", where the TYPE is one of the following: + - vol: A root or data volume + - snap: A snapshot volume + - tpl: A template spooled to the storage device +- Each volume's description field in the HPE Primera storage system will have a formatted key/value pair with metadata mappings for the Cloudstack volume definition (user volume name, volume uuid, account/project information) +- Each virtual volume's WWID will be stored in the volume's path field in Cloudstack + +Pure Flasharray API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This plugin enables Pure Flasharray storage systems with FiberChannel on KVM hypervisors. + +This documentation assumes you have the following configured in your environment before configuring a storage pool in cloudstack: + +- Deployed a Pure Flasharray storage system deployment supporting version 2 of the API. +- FiberChannel fabric and connectivity to every KVM host where volumes will be attached to virtual machines. +- Host definitions in the Pure Flasharray that match the name of the host in CloudStack. This can be fully-qualified or just the hostname. +- Hostgroup defined to match the group of hosts associated with the Cloudstack cluster. +- Username and password to access the API with at least Edit privileges. +- Pure Flasharray pod defined in the HPE Primera storage system where volumes and snapshots can be provisioned. NOTE: This "pod" is not the same as a "pod" in Cloudstack. + +When this storage pool is used with Compute or Disk Offerings, an administrator is +able to build an environment in which a root or data disk that a user creates leads +to the dynamic creation of a Virtual Volume in a Pure Flasharray storage system. +Such a virtual volume is associated with one (and only ever one) CloudStack volume, +so performance of the CloudStack volume does not vary depending on how heavily other +tenants are using the system. Volume migration is supported between different +Pure Flasharray Storage provider implementations, between Pure Flasharray Storage Pools and +NFS Storage Pools, and between other providers that support cross-provider volume migration. + +The createStoragePool API can be used to configure an Pure Flasharray storage pool with the +following parameters: + +- command=createStoragePool +- scope=[zone | cluster]. Note this must match your Hostset configuration (below) +- zoneid=[your zone id] +- podid=[your pod id, for cluster-wide primary storage] +- clusterid=[your cluster id, for cluster-wide primary storage] +- name=[name for primary storage] +- hypervisor=KVM +- provider=Flasharray +- capacitybytes=The total capacity bytes available to the pool (before overprovisioning configuration is applied). If provided, this must be less than the total available capacity of the Flasharray pod on the storage system. If its not provided, defaults to the Flasharray pod maximum space. +- url=[url to storage system] + +The url parameter contains the Pure Flasharray storage pool details, specified +in the following format: + +https://:@:/api?pod=&hostgroup=&api_skiptlsvalidation=" + +- API_USER: user name for API access to Pure Flasharray. This can also be configured with "details[0].api_username" in the createStoragePool API call. +- API_PASSWORD: password for API access to Pure Flasharray (password is URL encoded for example, '=' is represented as '%3D'). This can also be configured with "details[0].api_password" in the createStoragePool API call. +- STORAGE_IP_OR_HOST: hostname and IP address for API access to Pure Flasharray +- STORAGE_PORT: port for API access to Pure Flasharray +- STORAGE_POD_NAME: name of the storage system pod (NOT Cloudstack pod) in Pure Flasharray containing the hosts the cluster or zone has access to +- STORAGE_HOSTGROUP_NAME: name of the hostset in Pure Flasharray containing the hosts the cluster or zone has access to +- api_skiptlsvalidation: disable TLS certificate validation forPure Flasharray API access + +When a volume is created by the plugin, it will create bi-directional mappings in Cloudstack and the storage system: + +- Because of storage system volume name length constraints, the storage system volume name will be a formatted string formatted as: "----", where the TYPE is one of the following: + - vol: A root or data volume + - snap: A snapshot volume + - tpl: A template spooled to the storage device +- Each volume's description field in the Pure Flasharray storage system will have a formatted key/value pair with metadata mappings for the Cloudstack volume definition (user volume name, volume uuid, account/project information) +- Each virtual volume's WWID will be stored in the volume's path field in Cloudstack .. _add-secondary-storage: @@ -1347,7 +1612,7 @@ System Requirements for Secondary Storage - 100GB minimum capacity - A secondary storage device must be located in the same zone as the - guest VMs it serves. + Guest Instances it serves. - Each Secondary Storage server must be available to all hosts in the zone. @@ -1371,7 +1636,7 @@ add more servers to an existing zone. If you are using an Hyper-V host, ensure that you have created a SMB share. -#. Make sure you prepared the system VM template during Management +#. Make sure you prepared the system VM Template during Management Server installation. See `“Prepare the System VM Template” `_. @@ -1453,6 +1718,66 @@ zone: - Path. The path to the zone's Secondary Staging Store. +Add Object Storage +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can add object storage pools at any time to add more capacity or providers to CloudStack + + + +#. Make sure you have installed supported Object Storage provider and the Object Store is accessible from CloudStack Management Server + + +#. Log in to the CloudStack UI as root administrator. + +#. In the left navigation bar, click Infrastructure. + +#. In Object Storage, click View All. + +#. Click Add Object Storage. + +#. Fill in the following fields: + + - Name. Give the object store a descriptive name. + + - Provider. Choose provider and then fill in the related + fields which appear. The fields will vary depending on the object storage + provider; for more information, consult the provider's + documentation (such as the MinIO website). + + - URL: API endpoint of the object storage server + + - Access key: Credentials with access to admin API of the object storage server + + - Secret key: Credentials with access to admin API of the object storage server + + |AddObjectStore.png: Add Object Storage| + +See https://min.io/docs/minio/linux/index.html for MinIO Documentation + + +.. _register-templates: + +Register Cloud Templates +------------------------ + +For "KVM" hypervisor, admin can register cloud templates after Zone is enabled, through the optional step "Register Template" + + #. After selecting kvm hypervisor: + + |ZoneKVMRegisterTemplates.png: KVM Register Templates| + + #. Register Template step in Zone wizard: + + |ZoneRegisterTemplates.png: Zone Register Templates| + +**Notes** + +- Cloud image templates are hosted in http://download.cloudstack.org/templates/cloud-images/ +- Metadata for the available templates is stored on the management server at: `/usr/share/cloudstack-management/webapp/cloud-image-templates.json` +- `MD5 `_ and `SHA512 `_ checksums can be used to validate available cloud images for registration. + + .. _initialize-and-test: Initialize and Test @@ -1464,7 +1789,7 @@ of your network. When the initialization has completed successfully, the administrator's Dashboard should be displayed in the CloudStack UI. #. Verify that the system is ready. In the left navigation bar, select - Templates. Click on the CentOS 5.5 (64bit) no Gui (KVM) template. + Templates. Click on the CentOS 5.5 (64bit) no Gui (KVM) Template. Check to be sure that the status is "Download Complete." Do not proceed to the next step until this status is displayed. @@ -1474,9 +1799,9 @@ administrator's Dashboard should be displayed in the CloudStack UI. #. Choose the zone you just added. - #. In the template selection, choose the template to use in the VM. + #. In the Template selection, choose the Template to use in the instance. If this is a fresh installation, likely only the provided CentOS - template is available. + Template is available. #. Select a service offering. Be sure that the hardware you have allows starting the selected service offering. @@ -1484,27 +1809,27 @@ administrator's Dashboard should be displayed in the CloudStack UI. #. In data disk offering, if desired, add another data disk. This is a second volume that will be available to but not mounted in the guest. For example, in Linux on XenServer you will see /dev/xvdb - in the guest after rebooting the VM. A reboot is not required if + in the guest after rebooting the instance. A reboot is not required if you have a PV-enabled OS kernel in use. #. In default network, choose the primary network for the guest. In a trial installation, you would have only one option here. - #. Optionally give your VM a name and a group. Use any descriptive + #. Optionally give your instance a name and a group. Use any descriptive text you would like. - #. Click Launch VM. Your VM will be created and started. It might - take some time to download the template and complete the VM - startup. You can watch the VM’s progress in the Instances + #. Click Launch instance. Your instance will be created and started. It might + take some time to download the Template and complete the instance + startup. You can watch the instance's progress in the Instances screen. -#. To use the VM, click the View Console button. |ConsoleButton.png: +#. To use the instance, click the View Console button. |ConsoleButton.png: button to launch a console| - For more information about using VMs, including instructions for how - to allow incoming network traffic to the VM, start, stop, and delete - VMs, and move a VM from one host to another, see Working With Virtual - Machines in the Administrator’s Guide. + For more information about using instances, including instructions for how + to allow incoming network traffic to the instance, start, stop, and delete + instances, and move an instance from one host to another, see Working With Virtual + Machines in the Administrator's Guide. Congratulations! You have successfully completed a CloudStack Installation. @@ -1541,11 +1866,11 @@ Field Value ================================= ================================================================================ management.network.cidr A CIDR that describes the network that the management CIDRs reside on. This variable must be set for deployments that use vSphere. It is recommended to be set for other deployments as well. Example: 192.168.3.0/24. xen.setup.multipath For XenServer nodes, this is a true/false variable that instructs CloudStack to enable iSCSI multipath on the XenServer Hosts when they are added. This defaults to false. Set it to true if you would like CloudStack to enable multipath.If this is true for a NFS-based deployment multipath will still be enabled on the XenServer host. However, this does not impact NFS operation and is harmless. -secstorage.allowed.internal.sites This is used to protect your internal network from rogue attempts to download arbitrary files using the template download feature. This is a comma-separated list of CIDRs. If a requested URL matches any of these CIDRs the Secondary Storage VM will use the private network interface to fetch the URL. Other URLs will go through the public interface. We suggest you set this to 1 or 2 hardened internal machines where you keep your templates. For example, set it to 192.168.1.66/32. -use.local.storage Determines whether CloudStack will use storage that is local to the Host for data disks, templates, and snapshots. By default CloudStack will not use this storage. You should change this to true if you want to use local storage and you understand the reliability and feature drawbacks to choosing local storage. +secstorage.allowed.internal.sites This is used to protect your internal network from rogue attempts to download arbitrary files using the Template download feature. This is a comma-separated list of CIDRs. If a requested URL matches any of these CIDRs the Secondary Storage VM will use the private network interface to fetch the URL. Other URLs will go through the public interface. We suggest you set this to 1 or 2 hardened internal machines where you keep your Templates. For example, set it to 192.168.1.66/32. +use.local.storage Determines whether CloudStack will use storage that is local to the Host for data disks, Templates, and Snapshots. By default CloudStack will not use this storage. You should change this to true if you want to use local storage and you understand the reliability and feature drawbacks to choosing local storage. host This is the IP address of the Management Server. If you are using multiple Management Servers you should enter a load balanced IP address that is reachable via the private network. default.page.size Maximum number of items per page that can be returned by a CloudStack API command. The limit applies at the cloud level and can vary from cloud to cloud. You can override this with a lower value on a particular API call by using the page and pagesize API command parameters. For more information, see the Developer's Guide. Default: 500. -ha.tag The label you want to use throughout the cloud to designate certain hosts as dedicated HA hosts. These hosts will be used only for HA-enabled VMs that are restarting due to the failure of another host. For example, you could set this to ha\_host. Specify the ha.tag value asa host tag when you add a new host to the cloud. +ha.tag The label you want to use throughout the cloud to designate certain hosts as dedicated HA hosts. These hosts will be used only for HA-enabled instances that are restarting due to the failure of another host. For example, you could set this to ha\_host. Specify the ha.tag value asa host tag when you add a new host to the cloud. vmware.vcenter.session.timeout Determines the vCenter session timeout value by using this parameter. The default value is 20 minutes. Increase the timeout value to avoid timeout errors in VMware deployments because certain VMware operations take more than 20 minutes. ================================= ================================================================================ @@ -1580,9 +1905,31 @@ deployment. Setting Local Configuration Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the following steps to set local configuration parameters for an -account, zone, cluster, or primary storage. These values will override -the global configuration settings. +Configurations can also be set at more granular levels or scopes. + +#. Domain +#. Account +#. Zone +#. Cluster +#. Primary Storage +#. Secondary Storage + +All local settings can be configured at a global level as well. +If set, the local setting takes precedence over the global setting. + +Some configurations can be set at multiple levels or scopes. +For example, the following configuration parameters can be set at the +Zone scope and the Primary Storage scope. + +* pool.storage.capacity.disablethreshold +* pool.storage.allocated.resize.capacity.disablethreshold +* pool.storage.capacity.disablethreshold +* volume.resize.allowed.beyond.allocation + +In this case also the more granular setting (Primary Storage) +overrides the broader setting (Zone). + +Use the following steps to set local configuration parameters #. Log in to the UI as administrator. @@ -1602,6 +1949,9 @@ the global configuration settings. #. In the Actions column, click the Edit icon to modify a value. + .. note:: + Local configuration parameters will default to global configuration value when an explicit value is not set for them. Reset action for local configurations will also update their value to global configuration value. + Granular Global Configuration Parameters ---------------------------------------- @@ -1613,12 +1963,13 @@ account, cluster, and zone. .. cssclass:: table-striped table-bordered table-hover ======== ========================================================= ====================================================================================================================================== -Field Field Value +Scope Name Value ======== ========================================================= ====================================================================================================================================== account remote.access.vpn.client.iprange The range of IPs to be allocated to remotely access the VPN clients. The first IP in the range is used by the VPN server. -account allow.public.user.templates If false, users will not be able to create public templates. +account allow.public.user.templates If false, users will not be able to create public Templates. account use.system.public.ips If true and if an account has one or more dedicated public IP ranges, IPs are acquired from the system pool after all the IPs dedicated to the account have been consumed. account use.system.guest.vlans If true and if an account has one or more dedicated guest VLAN ranges, VLANs are allocated from the system pool after all the VLANs dedicated to the account have been consumed. +account router.service.offering Uuid of the service offering used by virtual routers; if NULL - system offering will be used cluster cluster.storage.allocated.capacity.notificationthreshold The percentage, as a value between 0 and 1, of allocated storage utilization above which alerts are sent that the storage is below the threshold. cluster cluster.storage.capacity.notificationthreshold The percentage, as a value between 0 and 1, of storage utilization above which alerts are sent that the available storage is below the threshold. cluster cluster.cpu.allocated.capacity.notificationthreshold The percentage, as a value between 0 and 1, of cpu utilization above which alerts are sent that the available CPU is below the threshold. @@ -1632,20 +1983,23 @@ cluster vmware.reserve.cpu Specify whe cluster vmware.reserve.mem Specify whether or not to reserve memory when not over-provisioning; In case of memory over-provisioning memory is always reserved. zone pool.storage.allocated.capacity.disablethreshold The percentage, as a value between 0 and 1, of allocated storage utilization above which allocators will disable that pool because the available allocated storage is below the threshold. -zone pool.storage.capacity.disablethreshold The percentage, as a value between 0 and 1, of storage utilization above which allocators will disable the pool because the available storage capacity is below the threshold. zone storage.overprovisioning.factor Used for storage over-provisioning calculation; available storage will be the mathematical product of actualStorageSize and storage.overprovisioning.factor. zone network.throttling.rate Default data transfer rate in megabits per second allowed in a network. -zone guest.domain.suffix Default domain name for VMs inside a virtual networks with a router. -zone router.template.xen Name of the default router template on Xenserver. -zone router.template.kvm Name of the default router template on KVM. -zone router.template.vmware Name of the default router template on VMware. -zone enable.dynamic.scale.vm Enable or diable dynamically scaling of a VM. +zone guest.domain.suffix Default domain name for instances inside a virtual networks with a router. +zone router.template.xen Name of the default router Template on Xenserver. +zone router.template.kvm Name of the default router Template on KVM. +zone router.template.vmware Name of the default router Template on VMware. +zone enable.dynamic.scale.vm Enable or disable dynamically scaling of a instance. zone use.external.dns Bypass internal DNS, and use the external DNS1 and DNS2 zone denied.routes Routes that are denied cannot be used for creating static routes for a VPC Private Gateway. -======== ========================================================= ====================================================================================================================================== +======== ========================================================= ====================================================================================================================================== .. |provisioning-overview.png: Conceptual overview of a basic deployment| image:: /_static/images/provisioning-overview.png .. |vsphereclient.png: vSphere client| image:: /_static/images/vsphere-client.png .. |addcluster.png: add a cluster| image:: /_static/images/add-cluster.png +.. |add-Host.png: Adding a KVM Host| image:: /_static/images/add-Host.png .. |ConsoleButton.png: button to launch a console| image:: /_static/images/console-icon.png +.. |AddObjectStore.png: Add Object Storage| image:: /_static/images/add-object-store.png +.. |ZoneKVMRegisterTemplates.png: KVM Register Templates| image:: /_static/images/zone-kvm-register-template.png +.. |ZoneRegisterTemplates.png: Zone Register Templates| image:: /_static/images/zone-register-templates.png diff --git a/source/installguide/encryption.rst b/source/installguide/encryption.rst index dae437556e..ec927f0a6a 100644 --- a/source/installguide/encryption.rst +++ b/source/installguide/encryption.rst @@ -64,25 +64,25 @@ highly recommended that you change these to more secure keys. Changing the Default Password Encryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Passwords are encoded when creating or updating users. CloudStack allows +Passwords are encoded when creating or updating Users. CloudStack allows you to determine the default encoding and authentication mechanism for -admin and user logins. Two new configurable lists have been +admin and User logins. Two new configurable lists have been introduced—userPasswordEncoders and userAuthenticators. userPasswordEncoders allows you to configure the order of preference for encoding passwords, whereas userAuthenticators allows you to configure -the order in which authentication schemes are invoked to validate user +the order in which authentication schemes are invoked to validate User passwords. -Additionally, the plain text user authenticator has been modified not to +Additionally, the plain text User authenticator has been modified not to convert supplied passwords to their md5 sums before checking them with the database entries. It performs a simple string comparison between retrieved and supplied login passwords instead of comparing the retrieved md5 hash of the stored password against the supplied md5 hash of the password because clients no longer hash the password. The following method determines what encoding scheme is used to encode the -password supplied during user creation or modification. +password supplied during User creation or modification. -When a new user is created, the user password is encoded by using the +When a new User is created, the User password is encoded by using the first valid encoder loaded as per the sequence specified in the ``UserPasswordEncoders`` property in the ``ComponentContext.xml`` or ``nonossComponentContext.xml`` files. The order of authentication @@ -122,11 +122,11 @@ desired order: In the above default ordering, SHA256Salt is used first for ``UserPasswordEncoders``. If the module is found and encoding returns a -valid value, the encoded password is stored in the user table's password +valid value, the encoded password is stored in the User table's password column. If it fails for any reason, the MD5UserAuthenticator will be tried next, and the order continues. For ``UserAuthenticators``, -SHA256Salt authentication is tried first. If it succeeds, the user is +SHA256Salt authentication is tried first. If it succeeds, the User is logged into the Management server. If it fails, md5 is tried next, and -attempts continues until any of them succeeds and the user logs in . If -none of them works, the user is returned an invalid credential message. +attempts continues until any of them succeeds and the User logs in . If +none of them works, the User is returned an invalid credential message. diff --git a/source/installguide/hypervisor/custom.rst b/source/installguide/hypervisor/custom.rst new file mode 100644 index 0000000000..4e7066c2c8 --- /dev/null +++ b/source/installguide/hypervisor/custom.rst @@ -0,0 +1,36 @@ +.. 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. + +Custom Hypervisor Installation +------------------------------ + +CloudStack allows adapting a new hypervisor plugin that may be developed privately. + +The new hypervisor type is internally named Custom to the CloudStack services. + + +The setting ‘hypervisor.custom.display.name’ allows administrators to set the display name of the hypervisor type. +The display name will be shown in the CloudStack UI and API. + + - In case the ‘hypervisor.list’ setting contains the display name of the new hypervisor type, the setting value is automatically updated after the ‘hypervisor.custom.display.name’ setting is updated. + + +The custom hypervisor type supports: + + - Direct downloads (the ability to download templates into primary storage from the hypervisor hosts without using secondary storage) + - Local storage (use hypervisor hosts local storage as primary storage) + - Template format: RAW format (the templates to be registered on the new hypervisor type must be in RAW format) + +The UI is also extended to display the new hypervisor type and the supported features listed above. diff --git a/source/installguide/hypervisor/hyperv.rst b/source/installguide/hypervisor/hyperv.rst index 075c73917e..d8a018074c 100644 --- a/source/installguide/hypervisor/hyperv.rst +++ b/source/installguide/hypervisor/hyperv.rst @@ -17,7 +17,7 @@ Host Hyper-V Installation ------------------------- -If you want to use Hyper-V hypervisor to run guest virtual machines, +If you want to use Hyper-V hypervisor to run Guest Instances, install Hyper-V on the hosts in your cloud. The instructions in this section doesn't duplicate Hyper-V Installation documentation. It provides the CloudStack-specific steps that are needed to prepare a @@ -85,7 +85,7 @@ start: | | y | the file share for the Hyper-V deployment will be | | | | the new folder created in the \\Shares on the | | | | selected volume. You can create sub-folders for both | -| | | CloudStack Primary and Secondary storage within the | +| | | CloudStack Primary and Secondary storage within the | | | | share location. When you select the profile for the | | | | file shares, ensure that you select SMB Share | | | | -Applications. This creates the file shares with | @@ -99,17 +99,17 @@ start: +------------+----------+------------------------------------------------------+ | Virtual | | If you are using Hyper-V 2012 R2, manually create an | | Switch | | external virtual switch before adding the host to | -| | | CloudStack. If the Hyper-V host is added to the Hyper-V | -| | | manager, select the host, then click Virtual Switch | -| | | Manager, then New Virtual Switch. In the External | -| | | Network, select the desired NIC adapter and click | -| | | Apply. | +| | | CloudStack. If the Hyper-V host is added to the | +| | | Hyper-V manager, select the host, then click Virtual | +| | | Switch Manager, then New Virtual Switch. In the | +| | | External Network, select the desired NIC adapter and | +| | | click Apply. | | | | | | | | If you are using Windows 2012 R2, virtual switch is | | | | created automatically. | +------------+----------+------------------------------------------------------+ | Virtual | | Take a note of the name of the virtual switch. You | -| Switch | | need to specify that when configuring CloudStack | +| Switch | | need to specify that when configuring CloudStack | | Name | | physical network labels. | +------------+----------+------------------------------------------------------+ | Hyper-V | | - Add the Hyper-V domain users to the Hyper-V | @@ -122,13 +122,13 @@ start: | | | - This domain user should be part of the Hyper-V | | | | Administrators and Local Administrators group on | | | | the Hyper-V hosts that are to be managed by | -| | | CloudStack. | +| | | CloudStack. | | | | | | | | - The Hyper-V Agent service runs with the | | | | credentials of this domain user account. | | | | | | | | - Specify the credential of the domain user while | -| | | adding a host to CloudStack so that it can manage | +| | | adding a host to CloudStack so that it can manage | | | | it. | | | | | | | | - Specify the credential of the domain user while | @@ -152,6 +152,9 @@ start: | Dial-in | | | +------------+----------+------------------------------------------------------+ +.. NOTE: For this kind of content it might be better to use a CSV table: +.. https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table + Hyper-V Installation Steps ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -179,7 +182,7 @@ Installing the CloudStack Agent on a Hyper-V Host The Hyper-V Agent helps CloudStack perform operations on the Hyper-V hosts. This Agent communicates with the Management Server and controls -all the instances on the host. Each Hyper-V host must have the Hyper-V +all the Instances on the host. Each Hyper-V host must have the Hyper-V Agent installed on it for successful interaction between the host and CloudStack. The Hyper-V Agent runs as a Windows service. Install the Agent on each host using the following steps. diff --git a/source/installguide/hypervisor/kvm.rst b/source/installguide/hypervisor/kvm.rst index 2448d603ca..d5dc3baa57 100644 --- a/source/installguide/hypervisor/kvm.rst +++ b/source/installguide/hypervisor/kvm.rst @@ -24,13 +24,11 @@ KVM is included with a variety of Linux-based operating systems. Although you are not required to run these distributions, the following are recommended: -- CentOS / RHEL: 7.X +- CentOS / RHEL / Binary-compatible variants: 8.X, 9.X, 10.X -- CentOS / RHEL / Binary-compatible variants: 8.X +- Ubuntu: 22.04 + -- Ubuntu: 18.04 + - -- openSUSE / SLES: 15.2 + +- openSUSE / SLES: 15.6 + The main requirement for KVM hypervisors is the libvirt and Qemu version. No matter what Linux distribution you are using, make sure the @@ -48,12 +46,14 @@ with OpenVswitch, the requirements are listed below - openvswitch: 1.7.1 or higher +Not all versions of Qemu/KVM may support dynamic scaling of Instances. Some combinations may result CPU or memory related failures during Instance deployment. + In addition, the following hardware requirements apply: - Within a single cluster, the hosts must be of the same distribution version. -- All hosts within a cluster must be homogenous. The CPUs must be of +- All hosts within a cluster must be homogeneous. The CPUs must be of the same type, count, and feature flags. - Must support HVM (Intel-VT or AMD-V enabled) @@ -64,7 +64,7 @@ In addition, the following hardware requirements apply: - At least 1 NIC -- When you deploy CloudStack, the hypervisor host must not have any VMs +- When you deploy CloudStack, the hypervisor host must not have any Instances already running. These will be destroy by CloudStack. @@ -72,7 +72,7 @@ KVM Installation Overview ~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to use the Linux Kernel Virtual Machine (KVM) hypervisor to -run guest virtual machines, install KVM on the host(s) in your cloud. +run Guest Instances, install KVM on the host(s) in your cloud. The material in this section doesn't duplicate KVM installation docs. It provides the CloudStack-specific steps that are needed to prepare a KVM host to work with CloudStack. @@ -88,7 +88,7 @@ host to work with CloudStack. .. warning:: Certain servers such as Dell provide the option to choose the Power Management Profile. The Active Power Controller enables Dell System DBPM (Demand Based Power Management) - which can restrict the visibility of the maximum CPU clock speed availble to the OS, + which can restrict the visibility of the maximum CPU clock speed available to the OS, which in turn can lead to CloudStack fetching the incorrect CPU speed of the server. To ensure that CloudStack can always fetch the maximum cpu speed on the server, ensure that "OS Control" is set as the Power Management Profile. @@ -108,7 +108,7 @@ Prepare the Operating System ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OS of the Host must be prepared to host the CloudStack Agent and run -KVM instances. +KVM Instances. #. Log in to your OS as root. @@ -147,7 +147,7 @@ KVM instances. .. parsed-literal:: - $ apt-get install chrony + $ apt install chrony In SUSE: @@ -158,16 +158,130 @@ KVM instances. #. Repeat all of these steps on every hypervisor host. .. warning:: - CloudStack |version| requires Java 11 JRE. Installing CloudStack agent will - automatically install Java 11, but it's good to explicitly confirm that the Java 11 + CloudStack |version| requires Java 17 JRE. Installing CloudStack agent will + automatically install Java 17, but it's good to explicitly confirm that the Java 17 is the selected/active one (in case you had a previous Java version already installed) with ``alternatives --config java``, after CloudStack agent is installed. +.. note:: + SUSE Linux Enterprise Server 15 (SP7) requires the following steps to install Java 17 and prepare the host. + +.. parsed-literal:: + + SUSEConnect --product sle-module-legacy/15.7/x86_64 + zypper install java-17-openjdk-17.0.15.0-150400.3.54.1 + SUSEConnect --product PackageHub/15.7/x86_64 + zypper install rng-tools + wget https://download.opensuse.org/repositories/openSUSE:/Leap:/15.2/standard/noarch/timezone-java-2020a-lp152.2.1.noarch.rpm + rpm -ivh timezone-java-2020a-lp152.2.1.noarch.rpm + + +Configure package repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CloudStack is only distributed from source from the official mirrors. +However, members of the CloudStack community may build convenience +binaries so that users can install Apache CloudStack without needing to +build from source. + +If you didn't follow the steps to build your own packages from source in +the sections for `“Building RPMs from Source” +<../building_from_source.html#building-rpms-from-source>`__ or +`“Building DEB packages” <../building_from_source.html#building-deb-packages>`__ +you may find pre-built DEB and RPM packages for your convenience linked from +the `downloads `_ page. + +.. note:: + These repositories contain both the Management Server and KVM Hypervisor + packages. + +RPM package repository +~~~~~~~~~~~~~~~~~~~~~~ + +There is a RPM package repository for CloudStack so you can easily +install on RHEL and SUSE based platforms. + +If you're using an RPM-based system, you'll want to add the Yum +repository so that you can install CloudStack with Yum. + +In RHEL or CentOS: + +Yum repository information is found under ``/etc/yum.repos.d``. You'll +see several ``.repo`` files in this directory, each one denoting a +specific repository. + +To add the CloudStack repository, create +``/etc/yum.repos.d/cloudstack.repo`` and insert the following +information. + +In the case of RHEL being used, you can replace 'centos' by 'rhel' in the value of baseurl + +.. parsed-literal:: + + [cloudstack] + name=cloudstack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Now you should now be able to install CloudStack using Yum. + +In SUSE: + +Zypper repository information is found under ``/etc/zypp/repos.d/``. You'll +see several ``.repo`` files in this directory, each one denoting a +specific repository. + +To add the CloudStack repository, create +``/etc/zypp/repos.d/cloudstack.repo`` and insert the following +information. + +.. parsed-literal:: + + [cloudstack] + name=cloudstack + baseurl=http://download.cloudstack.org/suse/$releasever/|version|/ + enabled=1 + gpgcheck=0 + + +Now you should now be able to install CloudStack using zypper. + + +DEB package repository +~~~~~~~~~~~~~~~~~~~~~~ + +You can add a DEB package repository to your apt sources with the +following commands. Replace the code name with your Ubuntu LTS version : +Ubuntu 22.04 (jammy), Ubuntu 24.04 (noble). + +Use your preferred editor and open (or create) +``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided +repository to the file (replace "trusty" with "xenial" or "bionic" if it is the case): + +.. parsed-literal:: + + deb https://download.cloudstack.org/ubuntu focal |version| + +We now have to add the public key to the trusted keys. + +.. parsed-literal:: + + wget -O - https://download.cloudstack.org/release.asc |sudo tee /etc/apt/trusted.gpg.d/cloudstack.asc + +Now update your local apt cache. + +.. parsed-literal:: + + sudo apt update + +Your DEB package repository should now be configured and ready for use. + Install and configure the Agent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To manage KVM instances on the host CloudStack uses a Agent. This Agent -communicates with the Management server and controls all the instances +To manage KVM Instances on the host CloudStack uses a Agent. This Agent +communicates with the Management server and controls all the Instances on the host. .. note:: @@ -187,7 +301,7 @@ In Ubuntu: .. parsed-literal:: - $ apt-get install cloudstack-agent + $ apt install cloudstack-agent In SUSE: @@ -195,6 +309,11 @@ In SUSE: $ zypper install cloudstack-agent +SUSE Linux Enterprise Server 15 (SP7) requires the following entry to be made in the /etc/cloudstack/agent/agent.properties file; the clock speed can be set to match the host CPU. + +.. parsed-literal:: + + host.cpu.manual.speed.mhz=2350 The host is now ready to be added to a cluster. This is covered in a later section, see :ref:`adding-a-host`. It is @@ -207,89 +326,119 @@ sudoers file: .. parsed-literal:: cloudstack ALL=NOPASSWD: /usr/bin/cloudstack-setup-agent - defaults:cloudstack !requiretty + Defaults:cloudstack !requiretty + +Please note that when adding the KVM host to your Cloudstack Management server, +the setup commands will be run with sudo, even with root account. +You should make sure that you are allowed to run binaries and sudo binaries. + +On security hardened machines, make sure that the following line is +commented-out in your sudoers file if it exists: + +.. parsed-literal:: + #Defaults noexec -Configure CPU model for KVM guest (Optional) +You may also want to make sure that sudo works by executing the following as +the user you want to register the KVM host with: + +.. parsed-literal:: + + sudo /usr/in/cloudstack-setup-agent --help + +Configure CPU model for KVM guests (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In additional,the CloudStack Agent allows host administrator to control -the guest CPU model which is exposed to KVM instances. By default, the -CPU model of KVM instance is likely QEMU Virtual CPU version x.x.x with -least CPU features exposed. There are a couple of reasons to specify the -CPU model: +The CloudStack Agent allows host administrators to control +the CPU model which is exposed to KVM instances. By default, the +default QEMU CPU models (``qemu32`` or ``qemu64``) will be used, which +are designed to be compatible with all hosts and, as a consequence, will +expose the least amount of CPU features possible. Therefore, there are +a couple of reasons to specify the CPU model: -- To maximise performance of instances by exposing new host CPU - features to the KVM instances; +- Maximize performance of instances by exposing new host CPU + features to them; and, -- To ensure a consistent default CPU across all machines,removing - reliance of variable QEMU defaults; +- Ensure a consistent default CPU across all machines, removing + reliance of variable QEMU defaults. -For the most part it will be sufficient for the host administrator to -specify the guest CPU config in the per-host configuration file -(/etc/cloudstack/agent/agent.properties). This will be achieved by -introducing following configuration parameters: +The guest CPU configuration can be configured per host in the +``/etc/cloudstack/agent/agent.properties`` configuration file +through the following properties: ``guest.cpu.mode``, ``guest.cpu.model`` and ``guest.cpu.features``. -.. parsed-literal:: +The ``guest.cpu.mode`` property accepts three possible values: + +#. **custom:** Allows the customization of the CPU model, which + should be defined in the ``guest.cpu.model`` setting. For instance: - guest.cpu.mode=custom|host-model|host-passthrough - guest.cpu.model=from /usr/share/libvirt/cpu_map.xml(only valid when guest.cpu.mode=custom) - guest.cpu.features=vmx ept aes smx mmx ht (space separated list of cpu flags to apply) + .. parsed-literal:: -There are three choices to fulfill the cpu model changes: + guest.cpu.mode=custom + guest.cpu.model=SandyBridge -#. **custom:** you can explicitly specify one of the supported named - model in /usr/share/libvirt/cpu\_map.xml + The available CPU models for a given architecture can be retrieved by + executing ``virsh cpu-models ``. The XML definition of each + available model can be accessed at the ``/usr/share/libvirt/cpu_map/`` + path of the KVM hosts. -#. **host-model:** libvirt will identify the CPU model in - /usr/share/libvirt/cpu\_map.xml which most closely matches the host, +#. **host-model:** Libvirt will identify the CPU model in + ``/usr/share/libvirt/cpu_map`` which most closely matches the host's CPU, and then request additional CPU flags to complete the match. This - should give close to maximum functionality/performance, which - maintaining good reliability/compatibility if the guest is migrated - to another host with slightly different host CPUs. - -#. **host-passthrough:** libvirt will tell KVM to passthrough the host - CPU with no modifications. The difference to host-model, instead of - just matching feature flags, every last detail of the host CPU is - matched. This gives absolutely best performance, and can be important - to some apps which check low level CPU details, but it comes at a + should give close to maximum functionality/performance and + maintains good reliability/compatibility if the guest is migrated + to another host with slightly different CPUs. + +#. **host-passthrough:** Libvirt will tell KVM to passthrough the host + CPU with no modifications. The difference to ``host-model`` is that, instead of + just matching CPU flags, every last detail of the host's CPU is + matched. This gives absolutely best performance and can be important + to some apps that check low level CPU details. However, it comes at a cost with respect to migration: the guest can only be migrated to an - exactly matching host CPU. + exactly matching host's CPU. + +Furthermore, there is the ``guest.cpu.features`` setting that can be used +to add or remove individual CPU features. It is important to highlight +that Libvirt complains about specifying a list of flags without a CPU model. +Therefore, to apply CPU flags in KVM, one of the following requirements must be met: + +- Define ``guest.cpu.mode=host-model`` and specify the flags; +- Define ``guest.cpu.mode=host-passthrough`` and specify the flags; or, +- Define ``guest.cpu.mode=custom``, ``guest.cpu.model=`` and specify the flags. Here are some examples: -- custom +- Custom CPU model: .. parsed-literal:: guest.cpu.mode=custom guest.cpu.model=SandyBridge -- host-model +- Host model: .. parsed-literal:: guest.cpu.mode=host-model -- host-passthrough +- Host passthrough, adding the ``vmx`` and ``avx`` CPU flags, and removing the ``mmx`` one: .. parsed-literal:: guest.cpu.mode=host-passthrough - guest.cpu.features=vmx + guest.cpu.features=vmx avx -mmx .. note:: - host-passthrough may lead to migration failure,if you have this problem, - you should use host-model or custom. guest.cpu.features will force cpu features - as a required policy so make sure to put only those features that are provided - by the host CPU. As your kvm cluster needs to be made up of homogenous nodes anyway - (see System Requirements), it might make most sense to use guest.cpu.mode=host-model - or guest.cpu.mode=host-passthrough. + ``host-passthrough`` may lead to migration failure. If you have this problem, + you should use ``host-model`` or a custom CPU model. ``guest.cpu.features`` will force CPU features + as a required policy, so make sure to put only those features that are provided + by the host's CPU. As your KVM cluster needs to be made up of homogeneous nodes + (see System Requirements), it might make most sense to use ``guest.cpu.mode=host-model`` + or ``guest.cpu.mode=host-passthrough``. Install and Configure libvirt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack uses libvirt for managing virtual machines. Therefore it is +CloudStack uses libvirt for managing Instances. Therefore it is vital that libvirt is configured correctly. Libvirt is a dependency of cloudstack-agent and should already be installed. @@ -297,8 +446,10 @@ cloudstack-agent and should already be installed. Please note that Cloudstack will automatically perform basic configuration of the agent and libvirt when the host is added. This is relevant if you are planning to automate the deployment and configuration of your KVM hosts. -#. In order to have live migration working libvirt has to listen for - unsecured TCP connections. We also need to turn off libvirts attempt +#. To avoid potential security attack to Instances, We need to turn + off libvirt to listen on insecure TCP port. CloudStack will automatically + set up cloud keystore and certificates when the host is added to cloudstack. + We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf`` @@ -310,7 +461,11 @@ cloudstack-agent and should already be installed. .. parsed-literal:: - listen_tcp = 1 + listen_tcp = 0 + + .. parsed-literal:: + + tls_port = "16514" .. parsed-literal:: @@ -324,8 +479,7 @@ cloudstack-agent and should already be installed. mdns_adv = 0 -#. Turning on "listen\_tcp" in libvirtd.conf is not enough, we have to - change the parameters as well: +#. We have to change the parameters as well: On RHEL or CentOS or SUSE modify ``/etc/sysconfig/libvirtd``: @@ -335,40 +489,55 @@ cloudstack-agent and should already be installed. #LIBVIRTD_ARGS="--listen" - On RHEL 8 / CentOS 8 / SUSE run the following command : + On RHEL 8 / CentOS 8 / SUSE / Ubuntu / Debian, run the following command : .. parsed-literal:: systemctl mask libvirtd.socket libvirtd-ro.socket libvirtd-admin.socket libvirtd-tls.socket libvirtd-tcp.socket - On Ubuntu modify ``/etc/default/libvirt-bin`` + On Ubuntu 20.04 or older, modify ``/etc/default/libvirtd`` Uncomment and change the following line .. parsed-literal:: - #env libvirtd_opts="" + #libvirtd_opts="" so it looks like: .. parsed-literal:: - env libvirtd_opts="-l" + libvirtd_opts="-l" -#. Restart libvirt + On Ubuntu 22.04 or newer version, modify ``/etc/default/libvirtd``: - In RHEL or CentOS or SUSE : + Uncomment the following line: .. parsed-literal:: - $ systemctl restart libvirtd + #LIBVIRTD_ARGS="--listen" - In Ubuntu: + Configure libvirt to connect to libvirtd and not to per-driver daemons, especially important on newer distros such as EL9, SUSE 15 SP7 and Ubuntu 24.04. + Edit ``/etc/libvirt/libvirt.conf`` and add the following: + + .. parsed-literal:: + remote_mode="legacy" + + On Ubuntu 24.04 or newer set libvirtd mode to traditional mode (see https://libvirt.org/manpages/libvirtd.html#system-socket-activation): + + .. parsed-literal:: + + systemctl mask libvirtd.socket libvirtd-ro.socket libvirtd-admin.socket libvirtd-tls.socket libvirtd-tcp.socket + + +#. Restart libvirt + + In RHEL or CentOS or SUSE or Ubuntu: .. parsed-literal:: - $ systemctl restart libvirt-bin + $ systemctl restart libvirtd Configure the Security Policies @@ -419,6 +588,10 @@ ensure the Agent has all the required permissions. $ setenforce permissive +.. note:: In a production environment, selinux should be set to enforcing + and the necessary selinux policies are created to allow the + services to run. + #. Configure Apparmor (Ubuntu) @@ -462,7 +635,7 @@ Configuring the Networking implementation in Linux. Please refer to the next section if you intend to use OpenVswitch -CloudStack uses the network bridges in conjunction with KVM to connect the guest instances to +CloudStack uses the network bridges in conjunction with KVM to connect the Guest Instances to each other and the outside world. They also are used to connect the System VMs to your infrastructure. @@ -482,7 +655,7 @@ There are many ways to configure your networking. Even within the scope of a giv network mode. Below are a few simple examples. .. note:: - Since Ubuntu 20.04 the standard for manging network connections is by + Since Ubuntu 20.04 the standard for managing network connections is by using NetPlan YAML files. Please refer to the Ubuntu man pages for further information and set up network connections figuratively. @@ -496,8 +669,8 @@ for the guest network. We assume that the hypervisor has one NIC (eth0) with one tagged VLAN trunked from the switch: -#. Native VLAN for management network (cloudbr0) -#. VLAN 200 for guest network of the instances (cloudbr1) +#. Native VLAN for Management Network (cloudbr0) +#. VLAN 200 for guest network of the Instances (cloudbr1) In this the following example we give the Hypervisor the IP-Address 192.168.42.11/24 with the gateway 192.168.42.1 @@ -667,7 +840,7 @@ Now we configure cloudbr0 and include the Management IP of the hypervisor. IPADDR=192.168.42.11 NETMASK=255.255.255.0 -Add the gatway in ``/etc/sysconfig/network/routes`` +Add the gateway in ``/etc/sysconfig/network/routes`` .. parsed-literal:: @@ -927,7 +1100,7 @@ Now we configure cloudbr0 and include the Management IP of the hypervisor. IPADDR=192.168.42.11 NETMASK=255.255.255.0 -Add the gatway in ``/etc/sysconfig/network/routes`` +Add the gateway in ``/etc/sysconfig/network/routes`` .. parsed-literal:: @@ -1003,6 +1176,52 @@ Modify the interfaces file to look like this: bridge_stp off bridge_maxwait 1 +If you are using *netplan* with Ubuntu, below is a sample configuration. + +.. parsed-literal:: + + $vi /etc/netplan/01-KVM-config.yaml + +Modify the *YAML* file to look like this: + +.. parsed-literal:: + + --- + network: + version: 2 + ethernets: + eth0: {} + eth1: {} + bridges: + cloudbr0: + addresses: + - 192.168.42.11/24 + dhcp4: false + routes: + - to: default + via: 192.168.42.1 + nameservers: + addresses: + - 8.8.8.8 + - 8.8.4.4 + search: [] + interfaces: + - eth0 + parameters: + stp: true + cloudbr1: + dhcp4: false + interfaces: + - eth1 + parameters: + stp: true + +To apply the above configuration: + +.. parsed-literal:: + + netplan apply + With this configuration you should be able to restart the network, although a reboot is recommended to see if everything works properly. @@ -1017,7 +1236,7 @@ Configure the network using OpenVswitch .. warning:: This is a very important section, please make sure you read this thoroughly. -In order to forward traffic to your instances you will need at least two +In order to forward traffic to your Instances you will need at least two bridges: *public* and *private*. By default these bridges are called *cloudbr0* and *cloudbr1*, but you @@ -1053,7 +1272,7 @@ VLANs: #. VLAN 100 for management of the hypervisor -#. VLAN 200 for public network of the instances (cloudbr0) +#. VLAN 200 for public network of the Instances (cloudbr0) #. VLAN 300 for private network of the instances (cloudbr1) @@ -1236,7 +1455,7 @@ We now have to configure the three VLAN bridges: NETMASK=255.255.255.0 -Add the gatway in ``/etc/sysconfig/network/routes`` +Add the gateway in ``/etc/sysconfig/network/routes`` .. parsed-literal:: @@ -1287,7 +1506,7 @@ using a firewall): #. 1798 -#. 16509, 16514 (libvirt) +#. 16514 (libvirt) #. 5900 - 6100 (VNC consoles) @@ -1311,10 +1530,6 @@ extra ports by executing the following iptable commands: $ iptables -I INPUT -p tcp -m tcp --dport 1798 -j ACCEPT -.. parsed-literal:: - - $ iptables -I INPUT -p tcp -m tcp --dport 16509 -j ACCEPT - .. parsed-literal:: $ iptables -I INPUT -p tcp -m tcp --dport 16514 -j ACCEPT @@ -1327,7 +1542,7 @@ extra ports by executing the following iptable commands: $ iptables -I INPUT -p tcp -m tcp --dport 49152:49216 -j ACCEPT -These iptable settings are not persistent accross reboots, we have to +These iptable settings are not persistent across reboots, we have to save them first. .. parsed-literal:: @@ -1359,10 +1574,6 @@ To open the required ports, execute the following commands: $ ufw allow proto tcp from any to any port 1798 -.. parsed-literal:: - - $ ufw allow proto tcp from any to any port 16509 - .. parsed-literal:: $ ufw allow proto tcp from any to any port 16514 @@ -1376,19 +1587,19 @@ To open the required ports, execute the following commands: $ ufw allow proto tcp from any to any port 49152:49216 .. note:: - By default UFW is not enabled on Ubuntu. Executing these commands with the - firewall disabled does not enable the firewall. + Since Ubuntu 22.04 LTS, the UFW's default policy for forwarding is set to "DROP". + Change it to "ACCEPT". - If you have an issue with ufw while using a bridged connection, - add those two lines at the end of the /etc/ufw/before.rules just before COMMIT +.. parsed-literal:: + sudo vi /etc/default/ufw .. parsed-literal:: - sudo vi /etc/ufw/before.rules + DEFAULT_FORWARD_POLICY="ACCEPT" .. parsed-literal:: - -A FORWARD -d 192.168.42.11 -j ACCEPT - -A FORWARD -s 192.168.42.11 -j ACCEPT + sudo ufw enable +UFW is disabled by default, so enabling it is recommended but optional. Additional Packages Required for Features ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1397,8 +1608,8 @@ Additional Packages Required for Features Secondary Storage Bypass ^^^^^^^^^^^^^^^^^^^^^^^^ -New in 4.11 is the ability to bypass storing a template on secondary storage, and -instead directly downloading a 'template' from an alternate remote location. +New in 4.11 is the ability to bypass storing a Template on secondary storage, and +instead directly downloading a 'Template' from an alternate remote location. In order to facilitate this the **Aria2** (https://aria2.github.io/) package must be installed on all of your KVM hosts. @@ -1406,29 +1617,43 @@ As this package often is not available in standard distribution repos, you will to install the package from your preferred source. -Volume snapshots +Volume Snapshots ^^^^^^^^^^^^^^^^ -CloudStack uses the qemu-img to perform snapshots. In CentOS >= 6.5, the qemu-img -supplied by RedHat/CentOS ceased to include a '-s' switch which performs snapshots. The +CloudStack uses the qemu-img to perform Snapshots. In CentOS >= 6.5, the qemu-img +supplied by RedHat/CentOS ceased to include a '-s' switch which performs Snapshots. The '-s' switch has been restored in latest CentOS/RHEL 7.x versions. -In order to be able to perform volume snapshots on CentOS 6.x (greater than 6.4) you must +In order to be able to perform Volume Snapshots on CentOS 6.x (greater than 6.4) you must replace your version of qemu-img with one which has been patched to include the '-s' switch. +Live Migration +^^^^^^^^^^^^^^ + +For Live Migration of the guests, it is better to configure the guest network bridge on +the same interface in the KVM hosts. In case, the guest network bridge is configured on +different interfaces in the KVM hosts, ensure the destination host doesn't have interface +with the interface name of guest network bridge in the source host. + + UEFI legacy / secureboot ^^^^^^^^^^^^^^^^^^^^^^^^ For deploying instances using UEFI legacy / secureboot, there are some further tasks to perform. -You can find further informations regarding prerequisites at the CloudStack Wiki + +In case of KVM, UEFI enabled hypervisor hosts must have the ``ovmf`` or +``edk2-ovmf`` package installed. + +You can find further information regarding prerequisites at the CloudStack Wiki (https://cwiki.apache.org/confluence/display/CLOUDSTACK/Enable+UEFI+booting+for+Instance) as well as limitations for using UEFI in CloudStack. -The options to deploy a instances using UEFI can be found in the "Advanced Mode" section -of the instance deployment wizard. +The options to deploy instances using UEFI can be found in the "Advanced Mode" section +of the instance deployment wizard, where users can specify the boot type and +boot mode for the selected valid template or ISO. Add the host to CloudStack ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/installguide/hypervisor/lxc.rst b/source/installguide/hypervisor/lxc.rst index 4ee94348e5..c937c1ebd1 100644 --- a/source/installguide/hypervisor/lxc.rst +++ b/source/installguide/hypervisor/lxc.rst @@ -49,7 +49,7 @@ In addition, the following hardware requirements apply: - Within a single cluster, the hosts must be of the same distribution version. -- All hosts within a cluster must be homogenous. The CPUs must be of +- All hosts within a cluster must be homogeneous. The CPUs must be of the same type, count, and feature flags. - Must support HVM (Intel-VT or AMD-V enabled) @@ -60,7 +60,7 @@ In addition, the following hardware requirements apply: - At least 1 NIC -- When you deploy CloudStack, the hypervisor host must not have any VMs +- When you deploy CloudStack, the hypervisor host must not have any Instances already running @@ -71,8 +71,8 @@ LXC does not have any native system VMs, instead KVM will be used to run system VMs. This means that your host will need to support both LXC and KVM, thus most of the installation and configuration will be identical to the KVM installation. The material in this section doesn't duplicate -KVM installation docs. It provides the CloudStack-specific steps that -are needed to prepare a KVM host to work with CloudStack. +information, so perform the steps in the Host KVM Installation section first +:ref:`host-kvm-installation`. .. warning:: Before continuing, make sure that you have applied the latest updates to @@ -97,7 +97,7 @@ Prepare the Operating System ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OS of the Host must be prepared to host the CloudStack Agent and run -KVM instances. +KVM Instances. #. Log in to your OS as root. @@ -123,231 +123,226 @@ KVM instances. NTP is required to synchronize the clocks of the servers in your cloud. Unsynchronized clocks can cause unexpected problems. - #. Install NTP +#. Install NTP - .. parsed-literal:: - - $ yum install ntp + In RHEL or CentOS: .. parsed-literal:: - $ apt-get install openntpd - -#. Repeat all of these steps on every hypervisor host. - - -Install and configure the Agent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To manage LXC instances on the host CloudStack uses a Agent. This Agent -communicates with the Management server and controls all the instances -on the host. - -First we start by installing the agent: - -In RHEL or CentOS: - -.. parsed-literal:: - - $ yum install -y epel-release - $ yum install cloudstack-agent - -In Ubuntu: - -.. parsed-literal:: + $ yum install chrony - $ apt-get install cloudstack-agent - -Next step is to update the Agent configuration setttings. The settings -are in ``/etc/cloudstack/agent/agent.properties`` - -#. Set the Agent to run in LXC mode: - - .. parsed-literal:: + In Ubuntu: - hypervisor.type=lxc + .. parsed-literal:: -#. Optional: If you would like to use direct networking (instead of the - default bridge networking), configure these lines: + $ apt install chrony - .. parsed-literal:: + In SUSE: - libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.DirectVifDriver + .. parsed-literal:: - .. parsed-literal:: + $ zypper install chrony - network.direct.source.mode=private +#. Repeat all of these steps on every hypervisor host. - .. parsed-literal:: - network.direct.device=eth0 +Configure package repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The host is now ready to be added to a cluster. This is covered in a -later section, see :ref:`adding-a-host`. It is -recommended that you continue to read the documentation before adding -the host! +CloudStack is only distributed from source from the official mirrors. +However, members of the CloudStack community may build convenience +binaries so that users can install Apache CloudStack without needing to +build from source. +If you didn't follow the steps to build your own packages from source in +the sections for `“Building RPMs from Source” +<../building_from_source.html#building-rpms-from-source>`__ or +`“Building DEB packages” <../building_from_source.html#building-deb-packages>`__ +you may find pre-built DEB and RPM packages for your convenience linked from +the `downloads `_ page. -Install and Configure libvirt -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + These repositories contain both the Management Server and KVM Hypervisor + packages. -CloudStack uses libvirt for managing virtual machines. Therefore it is -vital that libvirt is configured correctly. Libvirt is a dependency of -cloudstack-agent and should already be installed. +RPM package repository +~~~~~~~~~~~~~~~~~~~~~~ -#. In order to have live migration working libvirt has to listen for - unsecured TCP connections. We also need to turn off libvirts attempt - to use Multicast DNS advertising. Both of these settings are in - ``/etc/libvirt/libvirtd.conf`` +There is a RPM package repository for CloudStack so you can easily +install on RHEL and SUSE based platforms. - Set the following parameters: +If you're using an RPM-based system, you'll want to add the Yum +repository so that you can install CloudStack with Yum. - .. parsed-literal:: +In RHEL or CentOS: - listen_tls = 0 +Yum repository information is found under ``/etc/yum.repos.d``. You'll +see several ``.repo`` files in this directory, each one denoting a +specific repository. - .. parsed-literal:: +To add the CloudStack repository, create +``/etc/yum.repos.d/cloudstack.repo`` and insert the following +information. - listen_tcp = 1 +In the case of RHEL being used, you can replace 'centos' by 'rhel' in the value of baseurl - .. parsed-literal:: +.. parsed-literal:: - tcp_port = "16509" + [cloudstack] + name=cloudstack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 - .. parsed-literal:: +Now you should now be able to install CloudStack using Yum. - auth_tcp = "none" +In SUSE: - .. parsed-literal:: +Zypper repository information is found under ``/etc/zypp/repos.d/``. You'll +see several ``.repo`` files in this directory, each one denoting a +specific repository. - mdns_adv = 0 +To add the CloudStack repository, create +``/etc/zypp/repos.d/cloudstack.repo`` and insert the following +information. -#. Turning on "listen\_tcp" in libvirtd.conf is not enough, we have to - change the parameters as well: +.. parsed-literal:: - On RHEL or CentOS modify ``/etc/sysconfig/libvirtd``: + [cloudstack] + name=cloudstack + baseurl=http://download.cloudstack.org/suse/|version|/ + enabled=1 + gpgcheck=0 - Uncomment the following line: - .. parsed-literal:: +Now you should now be able to install CloudStack using zypper. - #LIBVIRTD_ARGS="--listen" - On Ubuntu: modify ``/etc/default/libvirt-bin`` +DEB package repository +~~~~~~~~~~~~~~~~~~~~~~ - Add "-l" to the following line +You can add a DEB package repository to your apt sources with the +following commands. Replace the code name with your Ubuntu LTS version : +Ubuntu 22.04 (jammy), Ubuntu 24.04 (noble). - .. parsed-literal:: +Use your preferred editor and open (or create) +``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided +repository to the file (replace "trusty" with "xenial" or "bionic" if it is the case): - libvirtd_opts="-d" +.. parsed-literal:: - so it looks like: + deb https://download.cloudstack.org/ubuntu focal |version| - .. parsed-literal:: +We now have to add the public key to the trusted keys. - libvirtd_opts="-d -l" - -#. In order to have the VNC Console work we have to make sure it will - bind on 0.0.0.0. We do this by editing ``/etc/libvirt/qemu.conf`` +.. parsed-literal:: - Make sure this parameter is set: + wget -O - https://download.cloudstack.org/release.asc |sudo tee /etc/apt/trusted.gpg.d/cloudstack.asc - .. parsed-literal:: +Now update your local apt cache. - vnc_listen = "0.0.0.0" +.. parsed-literal:: -#. Restart libvirt + sudo apt update - In RHEL or CentOS: +Your DEB package repository should now be configured and ready for use. - .. parsed-literal:: +Install and configure the Agent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ service libvirtd restart +To manage LXC Instances on the host CloudStack uses a Agent. This Agent +communicates with the Management server and controls all the Instances +on the host. - In Ubuntu: +.. note:: + Depending on your distribution you might need to add the corresponding package repository + for CloudStack. - .. parsed-literal:: +First we start by installing the agent: - $ service libvirt-bin restart +In RHEL or CentOS: +.. parsed-literal:: -Configure the Security Policies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ yum install -y epel-release + $ yum install cloudstack-agent -CloudStack does various things which can be blocked by security -mechanisms like AppArmor and SELinux. These have to be disabled to -ensure the Agent has all the required permissions. +In Ubuntu: -#. Configure SELinux (RHEL and CentOS) +.. parsed-literal:: - #. Check to see whether SELinux is installed on your machine. If not, - you can skip this section. + $ apt install cloudstack-agent - In RHEL or CentOS, SELinux is installed and enabled by default. - You can verify this with: +In SUSE: - .. parsed-literal:: +.. parsed-literal:: - $ rpm -qa | grep selinux + $ zypper install cloudstack-agent - #. Set the SELINUX variable in ``/etc/selinux/config`` to - "permissive". This ensures that the permissive setting will be - maintained after a system reboot. - In RHEL or CentOS: +If you're using a non-root user to add the LXC host, please add the user to +sudoers file: - .. parsed-literal:: +.. parsed-literal:: - $ vi /etc/selinux/config + cloudstack ALL=NOPASSWD: /usr/bin/cloudstack-setup-agent + Defaults:cloudstack !requiretty - Change the following line +Next step is to update the Agent configuration settings. The settings +are in ``/etc/cloudstack/agent/agent.properties`` - .. parsed-literal:: +#. Set the Agent to run in LXC mode: - SELINUX=enforcing + .. parsed-literal:: - to this + hypervisor.type=lxc - .. parsed-literal:: +#. Optional: If you would like to use direct networking (instead of the + default bridge networking), configure these lines: - SELINUX=permissive + .. parsed-literal:: - #. Then set SELinux to permissive starting immediately, without - requiring a system reboot. + libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.DirectVifDriver - .. parsed-literal:: + .. parsed-literal:: - $ setenforce permissive + network.direct.source.mode=private -#. Configure Apparmor (Ubuntu) + .. parsed-literal:: - #. Check to see whether AppArmor is installed on your machine. If - not, you can skip this section. + network.direct.device=eth0 - In Ubuntu AppArmor is installed and enabled by default. You can - verify this with: +The host is now ready to be added to a cluster. This is covered in a +later section, see :ref:`adding-a-host`. It is +recommended that you continue to read the documentation before adding +the host! - .. parsed-literal:: - $ dpkg --list 'apparmor' +Install and Configure libvirt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - #. Disable the AppArmor profiles for libvirt +CloudStack uses libvirt for managing System VM Instances, even in a LXC host. Therefore it is +vital that libvirt is configured correctly. Libvirt is a dependency of +cloudstack-agent and should already be installed. - .. parsed-literal:: +Please refer to :ref:`install-and-configure-libvirt` for the steps to install and configure +libvirt. Only the, perform the next steps. - $ ln -s /etc/apparmor.d/usr.sbin.libvirtd /etc/apparmor.d/disable/ +In Ubuntu: - .. parsed-literal:: +.. parsed-literal:: - $ ln -s /etc/apparmor.d/usr.lib.libvirt.virt-aa-helper /etc/apparmor.d/disable/ + apt install libvirt-daemon-driver-lxc -y - .. parsed-literal:: - $ apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd +Configure the Security Policies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. parsed-literal:: +CloudStack does various things which can be blocked by security +mechanisms like AppArmor and SELinux. These have to be disabled to +ensure the Agent has all the required permissions. - $ apparmor_parser -R /etc/apparmor.d/usr.lib.libvirt.virt-aa-helper +Please refer to :ref:`configure-the-security-policies` for the steps to install and configure libvirt. Configure the network bridges @@ -361,7 +356,7 @@ Configure the network bridges implementation in Linux. Please refer to the next section if you intend to use OpenVswitch -In order to forward traffic to your instances you will need at least two +In order to forward traffic to your Instances you will need at least two bridges: *public* and *private*. By default these bridges are called *cloudbr0* and *cloudbr1*, but you @@ -383,9 +378,9 @@ VLAN's: #. VLAN 100 for management of the hypervisor -#. VLAN 200 for public network of the instances (cloudbr0) +#. VLAN 200 for public network of the Instances (cloudbr0) -#. VLAN 300 for private network of the instances (cloudbr1) +#. VLAN 300 for private network of the Instances (cloudbr1) On VLAN 100 we give the Hypervisor the IP-Address 192.168.42.11/24 with the gateway 192.168.42.1 @@ -621,7 +616,7 @@ extra ports by executing the following iptable commands: $ iptables -I INPUT -p tcp -m tcp --dport 49152:49216 -j ACCEPT -These iptable settings are not persistent accross reboots, we have to +These iptable settings are not persistent across reboots, we have to save them first. .. parsed-literal:: diff --git a/source/installguide/hypervisor/vsphere.rst b/source/installguide/hypervisor/vsphere.rst index 9061e0612c..03a325d139 100644 --- a/source/installguide/hypervisor/vsphere.rst +++ b/source/installguide/hypervisor/vsphere.rst @@ -28,7 +28,7 @@ System Requirements for vSphere Hosts Software requirements: ^^^^^^^^^^^^^^^^^^^^^^ -- vSphere and vCenter, versions 6.0, 6.5 or 6.7. +- vSphere and vCenter (see `"Supported Hypervisor Versions" <../../releasenotes/compat.html#supported-hypervisor-versions>`_) vSphere Standard is recommended. Note however that customers need to consider the CPU constraints in place with vSphere licensing. See @@ -49,13 +49,13 @@ Software requirements: .. warning:: Apply All Necessary Hotfixes. The lack of up-do-date hotfixes can lead to - data corruption and lost VMs. + data corruption and lost Instances. .. note:: When using vSphere and vCenter versions 6.0 and 6.5 there is a limitation on - instance names with a sequence number between 99999 and 1000000. For example if you take - a snapshot of a VM, the expected filename will be different to what cloudstack expects. + Instance names with a sequence number between 99999 and 1000000. For example if you take + a Snapshot of an Instance, the expected filename will be different to what cloudstack expects. It is advisable to set the sequence number to 1M to prevent issues by executing the following script on your cloudstack database: @@ -74,7 +74,7 @@ Hardware requirements: - All hosts must be 64-bit and must support HVM (Intel-VT or AMD-V enabled). -- All hosts within a cluster must be homogenous. That means the CPUs +- All hosts within a cluster must be homogeneous. That means the CPUs must be of the same type, count, and feature flags. - 64-bit x86 CPU (more cores results in better performance) @@ -116,16 +116,16 @@ Requirements" `_) - and install it by following the VMware vSphere Installation Guide. + from the VMware/Broadcom Website and install it by following the VMware vSphere Installation Guide. #. Following installation, perform the following configuration, which are described in the next few sections: @@ -270,7 +268,7 @@ Configure Virtual Switch ^^^^^^^^^^^^^^^^^^^^^^^^ During the initial installation of an ESXi host a default virtual switch -vSwitch0 is created. You may need to create additional vSwiches depending +vSwitch0 is created. You may need to create additional vSwitches depending on your required architecture. CloudStack requires all ESXi hosts in the cloud to use consistently named virtual switches. If you change the default virtual switch name, you will need to configure @@ -443,19 +441,19 @@ switch's supervisor. It controls multiple VEMs as a single network device. The VSM is installed independent of the VEM and is deployed in redundancy mode as pairs or as a standalone appliance. The VEM is installed on each VMware ESXi server to provide packet-forwarding -capability. It provides each virtual machine with dedicated switch +capability. It provides each Instance with dedicated switch ports. This VSM-VEM architecture is analogous to a physical Cisco switch's supervisor (standalone or configured in high-availability mode) and multiple linecards architecture. Nexus 1000v switch uses vEthernet port profiles to simplify network -provisioning for virtual machines. There are two types of port profiles: +provisioning for Instances. There are two types of port profiles: Ethernet port profile and vEthernet port profile. The Ethernet port profile is applied to the physical uplink ports-the NIC ports of the physical NIC adapter on an ESXi server. The vEthernet port profile is -associated with the virtual NIC (vNIC) that is plumbed on a guest VM on -the ESXi server. The port profiles help the network administrators -define network policies which can be reused for new virtual machines. +associated with the virtual NIC (vNIC) that is plumbed on a guest Instance +on the ESXi server. The port profiles help the network administrators +define network policies which can be reused for new Instances. The Ethernet port profiles are created on the VSM and are represented as port groups on the vCenter server. @@ -575,13 +573,13 @@ these credentials while configuring Nexus virtual switch. **Management IP Address** This is the IP address of the VSM appliance. This is the IP address you -specify in the virtual switch IP Address field while configuting Nexus virtual +specify in the virtual switch IP Address field while configuring Nexus virtual switch. **SSL** Should be set to Enable.Always enable SSL. SSH is usually enabled by default during the VSM installation. However, check whether the SSH connection to the -VSM is working, without which CloudStack failes to connect to the VSM. +VSM is working, without which CloudStack fails to connect to the VSM. Creating a Port Profile @@ -608,7 +606,7 @@ Creating a Port Profile resources in the CloudStack environment. - You do not have to create any vEthernet port profiles – CloudStack - does that during VM deployment. + does that during Instance deployment. - Ensure that you create required port profiles to be used by CloudStack for different traffic types of CloudStack, such as @@ -878,7 +876,7 @@ The three fields to fill in are: **nexusdvs**: Represents Cisco Nexus 1000v distributed virtual switch. - If nothing specified (left empty), zone-level default virtual switchwould + If nothing specified (left empty), zone-level default virtual switch would be defaulted, based on the value of global parameter you specify. Following are the global configuration parameters: @@ -1042,10 +1040,10 @@ Applying Hotfixes to a VMware vSphere Host #. Move each of the ESXi hosts in the cluster to maintenance mode. - #. Ensure that all the VMs are migrated to other hosts in that + #. Ensure that all the Instances are migrated to other hosts in that cluster. - #. If there is only one host in that cluster, shutdown all the VMs + #. If there is only one host in that cluster, shutdown all the instances and move the host into maintenance mode. #. Apply the patch on the ESXi host. diff --git a/source/installguide/hypervisor/xenserver.rst b/source/installguide/hypervisor/xenserver.rst index 76112f5359..2610c330d4 100644 --- a/source/installguide/hypervisor/xenserver.rst +++ b/source/installguide/hypervisor/xenserver.rst @@ -18,7 +18,7 @@ Host Citrix XenServer Installation ---------------------------------- If you want to use the Citrix XenServer hypervisor to run guest virtual -machines, install XenServer 6.0 or XenServer 6.0.2 on the host(s) in +machines, install XenServer/XCP-ng 7.0 or later on the host(s) in your cloud. For an initial installation, follow the steps below. If you have previously installed XenServer and want to upgrade to another version, see :ref:`upgrading-xenserver-version`. @@ -31,14 +31,22 @@ System Requirements for XenServer Hosts See the Citrix Hardware Compatibility Guide: `http://hcl.xensource.com `_ - - XenServer 5.6 SP2 - - XenServer 6.0 - - XenServer 6.0.2 - - XenServer 6.1.0 - - XenServer 6.2.0 - - XenServer 6.5.0 - -- You must re-install Citrix XenServer if you are going to re-use a + - XenServer 7.0 + - XenServer 7.1 + - XenServer 7.5 + - XenServer 8.0 (not tested explicitly, but should work - see the release notes) + - XenServer 8.1 (not tested explicitly, but should work - see the release notes) + - XenServer 8.4 + - XCP-ng 7.4.0 + - XCP-ng 7.5.0 + - XCP-ng 7.6.0 + - XCP-ng 8.0.0 + - XCP-ng 8.1.0 + - XCP-ng 8.2.0 + - XCP-ng 8.3.0 + + +- You must re-install Citrix XenServer if you are going to reuse a host from a previous install. - Must support HVM (Intel-VT or AMD-V enabled) @@ -69,11 +77,11 @@ System Requirements for XenServer Hosts - Statically allocated IP Address -- When you deploy CloudStack, the hypervisor host must not have any VMs +- When you deploy CloudStack, the hypervisor host must not have any instances already running .. warning:: - The lack of up-to-date hotfixes can lead to data corruption and lost VMs. + The lack of up-to-date hotfixes can lead to data corruption and lost instances. XenServer Installation Steps @@ -98,11 +106,11 @@ Configure XenServer dom0 Memory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Configure the XenServer dom0 settings to allocate more memory to dom0. -This can enable XenServer to handle larger numbers of virtual machines. +This can enable XenServer to handle larger numbers of Instances. We recommend 2940 MB of RAM for XenServer dom0. For instructions on how -to do this, see `http://support.citrix.com/article/CTX126531 -`_. The article refers to -XenServer 5.6, but the same information applies to XenServer 6.0. +to do this, see `https://docs.citrix.com/en-us/xencenter/7-1/hosts-control-domain-memory.html +`_. The article refers to +XenServer 7.1 LTSR. Username and Password @@ -191,18 +199,18 @@ CSP functionality is already present in XenServer 6.1 For XenServer 6.0.2: - `http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz - `_ + `http://download.cloudstack.org/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz + `_ For XenServer 5.6 SP2: - `http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz - `_ + `http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz + `_ For XenServer 6.0: - `http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz - `_ + `http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz + `_ #. Extract the file: @@ -222,7 +230,7 @@ CSP functionality is already present in XenServer 6.1 .. parsed-literal:: - # xe-switch-network-backend bridge + # xe-switch-network-backend bridge Restart the host machine when prompted. @@ -449,32 +457,32 @@ CloudStack: Separate Storage Network for XenServer (Optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can optionally set up a separate storage network. This should be +You can optionally set up a separate Storage Network. This should be done first on the host, before implementing the bonding steps below. This can be done using one or two available NICs. With two NICs bonding may be done as above. It is the administrator's responsibility to set up -a separate storage network. +a separate Storage Network. -Give the storage network a different name-label than what will be given +Give the Storage Network a different name-label than what will be given for other networks. -For the separate storage network to work correctly, it must be the only +For the separate Storage Network to work correctly, it must be the only interface that can ping the primary storage device's IP address. For example, if eth0 is the management network NIC, ping -I eth0 must fail. In all deployments, secondary storage devices must be pingable from the management network NIC or bond. If a -secondary storage device has been placed on the storage network, it must -also be pingable via the storage network NIC or bond on the hosts as +secondary storage device has been placed on the Storage Network, it must +also be pingable via the Storage Network NIC or bond on the hosts as well. -You can set up two separate storage networks as well. For example, if +You can set up two separate Storage Networks as well. For example, if you intend to implement iSCSI multipath, dedicate two non-bonded NICs to multipath. Each of the two networks needs a unique name-label. If no bonding is done, the administrator must set up and name-label the -separate storage network on all hosts (masters and slaves). +separate Storage Network on all hosts (masters and slaves). -Here is an example to set up eth5 to access a storage network on +Here is an example to set up eth5 to access a Storage Network on 172.16.0.0/24. .. parsed-literal:: @@ -492,7 +500,7 @@ NIC Bonding for XenServer (Optional) XenServer supports Source Level Balancing (SLB) NIC bonding. Two NICs can be bonded together to carry public, private, and guest traffic, or -some combination of these. Separate storage networks are also possible. +some combination of these. Separate Storage Networks are also possible. Here are some example supported configurations: - 2 NICs on private, 2 NICs on public, 2 NICs on storage @@ -648,6 +656,10 @@ Now the bonds are set up and configured properly across the cluster. Upgrading XenServer Versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + This section has been updated and the upgrade steps shown below + have been tested with XenServer 6.5 and up (i.e. upgrading from 6.5 to 7.1 and later) + This section tells how to upgrade XenServer software on CloudStack hosts. The actual upgrade is described in XenServer documentation, but there are some additional steps you must perform before and after the @@ -659,138 +671,104 @@ upgrade. To upgrade XenServer: -#. Upgrade the database. On the Management Server node: - - #. Back up the database: - - .. parsed-literal:: - - # mysqldump --user=root --databases cloud > cloud.backup.sql - # mysqldump --user=root --databases cloud_usage > cloud_usage.backup.sql - - #. You might need to change the OS type settings for VMs running on - the upgraded hosts. - - - If you upgraded from XenServer 5.6 GA to XenServer 5.6 SP2, - change any VMs that have the OS type CentOS 5.5 (32-bit), - Oracle Enterprise Linux 5.5 (32-bit), or Red Hat Enterprise - Linux 5.5 (32-bit) to Other Linux (32-bit). Change any VMs that - have the 64-bit versions of these same OS types to Other Linux - (64-bit). - - - If you upgraded from XenServer 5.6 SP2 to XenServer 6.0.2, - change any VMs that have the OS type CentOS 5.6 (32-bit), - CentOS 5.7 (32-bit), Oracle Enterprise Linux 5.6 (32-bit), - Oracle Enterprise Linux 5.7 (32-bit), Red Hat Enterprise Linux - 5.6 (32-bit) , or Red Hat Enterprise Linux 5.7 (32-bit) to - Other Linux (32-bit). Change any VMs that have the 64-bit - versions of these same OS types to Other Linux (64-bit). - - - If you upgraded from XenServer 5.6 to XenServer 6.0.2, do all - of the above. - - #. Restart the Management Server and Usage Server. You only need to - do this once for all clusters. - - .. parsed-literal:: - - # service cloudstack-management start - # service cloudstack-usage start - #. Disconnect the XenServer cluster from CloudStack. - #. Log in to the CloudStack UI as root. + #. Log in to the CloudStack UI as admin. #. Navigate to the XenServer cluster, and click Actions – Unmanage. - #. Watch the cluster status until it shows Unmanaged. + #. Watch the cluster status until it shows "Unmanaged". + + This ensures that any actions against hosts in this cluster + are not possible (i.e. instance stop/start/snapshot, etc.) and CloudStack will + "ignore" the cluster (i.e. it will not react if the host goes down, etc.). + + This is important since in the following steps we will be migrating instances out of band, + upgrading and rebooting each host in the cluster, etc. #. Log in to one of the hosts in the cluster, and run this command to - clean up the VLAN: + clean up the VLAN (all VLANs and networks are attempted to be removed, but only + the ones with no VIFs/PIFs are actually removed - i.e. we are doing a bit of housekeeping) .. parsed-literal:: - # . /opt/xensource/bin/cloud-clean-vlan.sh + # /opt/cloud/bin/cloud-clean-vlan.sh -#. Still logged in to the host, run the upgrade preparation script: +#. Still logged in to the host, run the upgrade preparation script which will ensure that all existing VLANs and networks are propagated to all hosts, eject ISOs from all instances and also "fake" presence of PV drivers on PV instances - all of this is done to enable live migration of instances between hosts later: .. parsed-literal:: - # /opt/xensource/bin/cloud-prepare-upgrade.sh + # /opt/cloud/bin/cloud-prepare-upgrade.sh Troubleshooting: If you see the error "can't eject CD," log in to the - VM and umount the CD, then run the script again. + instance and umount the CD, then run the script again. -#. Upgrade the XenServer software on all hosts in the cluster. Upgrade - the master first. +#. Upgrade the XenServer software on all hosts in the cluster. Upgrade the master first. Do NOT put the pool master host into the Maintenance mode as this will move the pool master role to another host. - #. Live migrate all VMs on this host to other hosts. See the + #. Live migrate all instances on this host to other hosts. See the instructions for live migration in the Administrator's Guide. Troubleshooting: You might see the following error when you - migrate a VM: + migrate a instance: .. parsed-literal:: [root@xenserver-qa-2-49-4 ~]# xe vm-migrate live=true host=xenserver-qa-2-49-5 vm=i-2-8-VM - You attempted an operation on a VM which requires PV drivers to be installed but the drivers were not detected. + You attempted an operation on a instance which requires PV drivers to be installed but the drivers were not detected. vm: b6cf79c8-02ee-050b-922f-49583d9f1a14 (i-2-8-VM) To solve this issue, run the following: .. parsed-literal:: - # /opt/xensource/bin/make_migratable.sh b6cf79c8-02ee-050b-922f-49583d9f1a14 + # /opt/cloud/bin/make_migratable.sh b6cf79c8-02ee-050b-922f-49583d9f1a14 #. Reboot the host. - #. Upgrade to the newer version of XenServer. Use the steps in - XenServer documentation. + #. Upgrade to the newer version of XenServer using an ISO file. This will essentially backup the current root partition + of the host and install a new version of hypervisor, while preserving the existing instances and configuration. Use the steps in XenServer documentation. - #. After the upgrade is complete, copy the following files from the - management server to this host, in the directory locations shown - below: + #. After the upgrade is complete and the host boots, create the destination folder "/opt/cloud/bin/" on the host + and copy the following files from the management server to this host, in the directory locations shown below: .. cssclass:: table-striped table-bordered table-hover ================================================================================= ======================================= Copy this Management Server file To this location on the XenServer host ================================================================================= ======================================= - /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/xenserver60/NFSSR.py /opt/xensource/sm/NFSSR.py - /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/setupxenserver.sh /opt/xensource/bin/setupxenserver.sh - /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/make\_migratable.sh /opt/xensource/bin/make\_migratable.sh - /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/cloud-clean-vlan.sh /opt/xensource/bin/cloud-clean-vlan.sh + /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/setupxenserver.sh /opt/cloud/bin/setupxenserver.sh + /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/make\_migratable.sh /opt/cloud/bin/make\_migratable.sh + /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/cloud-clean-vlan.sh /opt/cloud/bin/cloud-clean-vlan.sh ================================================================================= ======================================= - #. Run the following script: + #. Run the following script, which will configure a few things on the freshly upgraded XenServer host + (disable IPv6, configure VNC related firewall settings, configure a few network settings, clear the heartbeat file, etc.): .. parsed-literal:: - # /opt/xensource/bin/setupxenserver.sh + # /opt/cloud/bin/setupxenserver.sh - Troubleshooting: If you see the following error message, you can - safely ignore it. + Troubleshooting: If you see the following error messages, you can + safely ignore them. .. parsed-literal:: - mv: cannot stat `/etc/cron.daily/logrotate`: No such file or directory + iptables: Bad rule (does a matching rule exist in that chain?). + sed: can't read /opt/xensource/libexec/qemu-dm-wrapper: No such file or directory + mv: cannot stat ‘/etc/cron.daily/logrotate’: No such file or directory #. Plug in the storage repositories (physical block devices) to the - XenServer host: + XenServer host (although all of them should already be plugged in): .. parsed-literal:: - # for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk '{print $NF}'`; do xe pbd-plug uuid=$pbd ; done + # for pbd in $(xe pbd-list currently-attached=false | grep ^uuid | awk '{print $NF}'); do xe pbd-plug uuid=$pbd ; done - .. note:: - If you add a host to this XenServer pool, you need to migrate all VMs - on this host to other hosts, and eject this host from XenServer pool. -#. Repeat these steps to upgrade every host in the cluster to the same - version of XenServer. +#. Repeat these steps to upgrade every host in the cluster to the same version of XenServer. -#. Run the following command on one host in the XenServer cluster to - clean up the host tags: +#. When all of the hosts in the pool are upgraded, run the following command on one host in the XenServer cluster to + clean up the host tags (this will make sure ACS later copies the rest of the required scripts and plugins to each host): .. parsed-literal:: @@ -803,13 +781,14 @@ To upgrade XenServer: #. Reconnect the XenServer cluster to CloudStack. - #. Log in to the CloudStack UI as root. + #. Log in to the CloudStack UI as admin. #. Navigate to the XenServer cluster, and click Actions – Manage. - #. Watch the status to see that all the hosts come up. + #. Watch the status to see that all the hosts come "Up" (it can take a few minutes, as it takes time for CloudStack to copy + all of the required scripts and plugins to the upgraded hosts) -#. After all hosts are up, run the following on one host in the cluster: +#. Optionally, after all hosts are "Up", run the following on one host in the cluster: .. parsed-literal:: diff --git a/source/installguide/locale/pot/building_from_source.pot b/source/installguide/locale/pot/building_from_source.pot index 14333758ee..8cd704cf30 100644 --- a/source/installguide/locale/pot/building_from_source.pot +++ b/source/installguide/locale/pot/building_from_source.pot @@ -233,7 +233,7 @@ msgstr "" #: ../../building_from_source.rst:194 # 283980d16b48466bb2a2d3b17ff1fede -msgid "While we have defined, and you have presumably already installed the bootstrap prerequisites, there are a number of build time prerequisites that need to be resolved. CloudStack uses maven for dependency resolution. You can resolve the buildtime depdencies for CloudStack by running:" +msgid "While we have defined, and you have presumably already installed the bootstrap prerequisites, there are a number of build time prerequisites that need to be resolved. CloudStack uses maven for dependency resolution. You can resolve the buildtime dependencies for CloudStack by running:" msgstr "" #: ../../building_from_source.rst:204 @@ -418,7 +418,7 @@ msgstr "" #: ../../building_from_source.rst:446 # d9d9d34be2604c18a3b9107dbf384181 -msgid "You may also need to download `vhd-util `_, which was removed due to licensing issues. You'll copy vhd-util to the ``scripts/vm/hypervisor/xenserver/`` directory." +msgid "You may also need to download `vhd-util `_, which was removed due to licensing issues. You'll copy vhd-util to the ``scripts/vm/hypervisor/xenserver/`` directory." msgstr "" #: ../../building_from_source.rst:451 diff --git a/source/installguide/locale/pot/configuration.pot b/source/installguide/locale/pot/configuration.pot index 9c4db09afe..17ba070c69 100644 --- a/source/installguide/locale/pot/configuration.pot +++ b/source/installguide/locale/pot/configuration.pot @@ -1674,7 +1674,7 @@ msgstr "" #: ../../configuration.rst:1264 # febca3ed36dc41f0bfe48a3170c1b282 -msgid "The createStoragePool API has been augmented to support plugable storage providers. The following is a list of parameters to use when adding storage to CloudStack that is based on the SolidFire plug-in:" +msgid "The createStoragePool API has been augmented to support pluggable storage providers. The following is a list of parameters to use when adding storage to CloudStack that is based on the SolidFire plug-in:" msgstr "" #: ../../configuration.rst:1268 diff --git a/source/installguide/locale/pot/hypervisor/kvm.pot b/source/installguide/locale/pot/hypervisor/kvm.pot index 7b75d4ce44..6a0a74a396 100644 --- a/source/installguide/locale/pot/hypervisor/kvm.pot +++ b/source/installguide/locale/pot/hypervisor/kvm.pot @@ -83,7 +83,7 @@ msgstr "" #: ../../hypervisor/kvm.rst:52 # fc001eaf8fb842d7adbbf5bb977be8fd -msgid "All hosts within a cluster must be homogenous. The CPUs must be of the same type, count, and feature flags." +msgid "All hosts within a cluster must be homogeneous. The CPUs must be of the same type, count, and feature flags." msgstr "" #: ../../hypervisor/kvm.rst:55 @@ -320,7 +320,7 @@ msgstr "" #: ../../hypervisor/kvm.rst:243 # ed8dd766459147cbb85ff50d90c4b80e -msgid "In order to have live migration working libvirt has to listen for unsecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" +msgid "In order to have live migration working libvirt has to listen for insecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" msgstr "" #: ../../hypervisor/kvm.rst:248 @@ -735,7 +735,7 @@ msgstr "" #: ../../hypervisor/kvm.rst:836 # f47cb1aac5b0422ea1409fd01b64e2db -msgid "These iptable settings are not persistent accross reboots, we have to save them first." +msgid "These iptable settings are not persistent across reboots, we have to save them first." msgstr "" #: ../../hypervisor/kvm.rst:845 diff --git a/source/installguide/locale/pot/hypervisor/lxc.pot b/source/installguide/locale/pot/hypervisor/lxc.pot index 81fef09a88..ec6e8ef5fa 100644 --- a/source/installguide/locale/pot/hypervisor/lxc.pot +++ b/source/installguide/locale/pot/hypervisor/lxc.pot @@ -80,7 +80,7 @@ msgstr "" #: ../../hypervisor/lxc.rst:52 # 9a162b24f7fd499c9793ac22d8cd360f -msgid "All hosts within a cluster must be homogenous. The CPUs must be of the same type, count, and feature flags." +msgid "All hosts within a cluster must be homogeneous. The CPUs must be of the same type, count, and feature flags." msgstr "" #: ../../hypervisor/lxc.rst:55 @@ -230,7 +230,7 @@ msgstr "" #: ../../hypervisor/lxc.rst:160 # 04df1ba82d804c3e93844dbf7cdd829d -msgid "Next step is to update the Agent configuration setttings. The settings are in ``/etc/cloudstack/agent/agent.properties``" +msgid "Next step is to update the Agent configuration settings. The settings are in ``/etc/cloudstack/agent/agent.properties``" msgstr "" #: ../../hypervisor/lxc.rst:163 @@ -262,7 +262,7 @@ msgstr "" #: ../../hypervisor/lxc.rst:197 # f54bd7715b5441f687683613bff00956 -msgid "In order to have live migration working libvirt has to listen for unsecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" +msgid "In order to have live migration working libvirt has to listen for insecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" msgstr "" #: ../../hypervisor/lxc.rst:202 @@ -591,7 +591,7 @@ msgstr "" #: ../../hypervisor/lxc.rst:623 # d20a63121d8d4a90b51c2e5eb1dc1b8e -msgid "These iptable settings are not persistent accross reboots, we have to save them first." +msgid "These iptable settings are not persistent across reboots, we have to save them first." msgstr "" #: ../../hypervisor/lxc.rst:632 diff --git a/source/installguide/locale/pot/hypervisor/vsphere.pot b/source/installguide/locale/pot/hypervisor/vsphere.pot index 2935e3a990..c3389a1553 100644 --- a/source/installguide/locale/pot/hypervisor/vsphere.pot +++ b/source/installguide/locale/pot/hypervisor/vsphere.pot @@ -78,7 +78,7 @@ msgstr "" #: ../../hypervisor/vsphere.rst:66 # 0a5dabc432dc454396baf7e656897fe6 -msgid "All hosts within a cluster must be homogenous. That means the CPUs must be of the same type, count, and feature flags." +msgid "All hosts within a cluster must be homogeneous. That means the CPUs must be of the same type, count, and feature flags." msgstr "" #: ../../hypervisor/vsphere.rst:69 @@ -163,7 +163,7 @@ msgstr "" #: ../../hypervisor/vsphere.rst:114 # 311e91fb341e4d30a649ba13d80e2e72 -msgid "You must re-install VMware ESXi if you are going to re-use a host from a previous install." +msgid "You must re-install VMware ESXi if you are going to reuse a host from a previous install." msgstr "" #: ../../hypervisor/vsphere.rst:117 @@ -830,12 +830,12 @@ msgstr "" #: ../../hypervisor/vsphere.rst:507 # c42b39990d6e4d0589467d0a4ff5be4c -msgid "**Management IP Address** This is the IP address of the VSM appliance. This is the IP address you specify in the virtual switch IP Address field while configuting Nexus virtual switch." +msgid "**Management IP Address** This is the IP address of the VSM appliance. This is the IP address you specify in the virtual switch IP Address field while configuring Nexus virtual switch." msgstr "" #: ../../hypervisor/vsphere.rst:512 # 26a1722f2c004284958a7d40035272d8 -msgid "**SSL** Should be set to Enable.Always enable SSL. SSH is usually enabled by default during the VSM installation. However, check whether the SSH connection to the VSM is working, without which CloudStack failes to connect to the VSM." +msgid "**SSL** Should be set to Enable.Always enable SSL. SSH is usually enabled by default during the VSM installation. However, check whether the SSH connection to the VSM is working, without which CloudStack fails to connect to the VSM." msgstr "" #: ../../hypervisor/vsphere.rst:519 diff --git a/source/installguide/locale/pot/hypervisor/xenserver.pot b/source/installguide/locale/pot/hypervisor/xenserver.pot index 7c7a65bdc6..73e52725c8 100644 --- a/source/installguide/locale/pot/hypervisor/xenserver.pot +++ b/source/installguide/locale/pot/hypervisor/xenserver.pot @@ -63,7 +63,7 @@ msgstr "" #: ../../hypervisor/xenserver.rst:40 # 5dee06ed5f2f472f9e0979ddbb241a63 -msgid "You must re-install Citrix XenServer if you are going to re-use a host from a previous install." +msgid "You must re-install Citrix XenServer if you are going to reuse a host from a previous install." msgstr "" #: ../../hypervisor/xenserver.rst:43 @@ -253,7 +253,7 @@ msgstr "" #: ../../hypervisor/xenserver.rst:193 # c7d858231a3142109c09bfcc3340078b -msgid "`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor/xenserver.rst:196 @@ -263,7 +263,7 @@ msgstr "" #: ../../hypervisor/xenserver.rst:198 # beac106ea20e420cae0ca5acb450646b -msgid "`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor/xenserver.rst:201 @@ -273,7 +273,7 @@ msgstr "" #: ../../hypervisor/xenserver.rst:203 # 998fd323b14c42149cc6633f4df39b83 -msgid "`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor/xenserver.rst:207 diff --git a/source/installguide/locale/pot/hypervisor_installation.pot b/source/installguide/locale/pot/hypervisor_installation.pot index b0cb2726ae..2dfbdfa1aa 100644 --- a/source/installguide/locale/pot/hypervisor_installation.pot +++ b/source/installguide/locale/pot/hypervisor_installation.pot @@ -104,7 +104,7 @@ msgstr "" #: ../../hypervisor_installation.rst:3366 # 86c9ea55ffec4f399b8e7918b7bb43d0 # e392215de57d4843958e657b3d6d64c7 -msgid "All hosts within a cluster must be homogenous. The CPUs must be of the same type, count, and feature flags." +msgid "All hosts within a cluster must be homogeneous. The CPUs must be of the same type, count, and feature flags." msgstr "" #: ../../hypervisor_installation.rst:75 @@ -423,7 +423,7 @@ msgstr "" #: ../../hypervisor_installation.rst:3539 # ff42e0ea9cf64b509d310c0071086352 # 5b89b062abbe4cc89b7fd10ece8eb9e8 -msgid "In order to have live migration working libvirt has to listen for unsecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" +msgid "In order to have live migration working libvirt has to listen for insecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in ``/etc/libvirt/libvirtd.conf``" msgstr "" #: ../../hypervisor_installation.rst:308 @@ -968,7 +968,7 @@ msgstr "" #: ../../hypervisor_installation.rst:3983 # d68286a4499a42d0af59d58cf3307ce8 # cabb0609f32c4af983aec749c9a3bde6 -msgid "These iptable settings are not persistent accross reboots, we have to save them first." +msgid "These iptable settings are not persistent across reboots, we have to save them first." msgstr "" #: ../../hypervisor_installation.rst:911 @@ -1239,7 +1239,7 @@ msgstr "" #: ../../hypervisor_installation.rst:1022 # 7f67c993b17a4b25a8b436331132a38b -msgid "You must re-install Citrix XenServer if you are going to re-use a host from a previous install." +msgid "You must re-install Citrix XenServer if you are going to reuse a host from a previous install." msgstr "" #: ../../hypervisor_installation.rst:1031 @@ -1385,7 +1385,7 @@ msgstr "" #: ../../hypervisor_installation.rst:1181 # 54880e3acb4945b4ae3d3fb251252130 -msgid "`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor_installation.rst:1183 @@ -1395,7 +1395,7 @@ msgstr "" #: ../../hypervisor_installation.rst:1185 # b1533b01dec04d8ea37cb07d541d8013 -msgid "`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor_installation.rst:1187 @@ -1405,7 +1405,7 @@ msgstr "" #: ../../hypervisor_installation.rst:1189 # bc80c4fa363248c292882b511d90808a -msgid "`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz `_" +msgid "`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz `_" msgstr "" #: ../../hypervisor_installation.rst:1193 @@ -1668,7 +1668,7 @@ msgstr "" #: ../../hypervisor_installation.rst:1484 # 21486bfc4a50447a974137680f2e8750 msgid "If no bonding is done, the administrator must set up and name-label the separate storage network on all hosts (masters and slaves)." -msgstr "" +msgstr " #: ../../hypervisor_installation.rst:1487 # e74b734827c148e4abf67add41daf5fa @@ -2573,7 +2573,7 @@ msgstr "" #: ../../hypervisor_installation.rst:2258 # 444698b909b14c1bafa79d28ca6d0e0c -msgid "All hosts within a cluster must be homogenous. That means the CPUs must be of the same type, count, and feature flags." +msgid "All hosts within a cluster must be homogeneous. That means the CPUs must be of the same type, count, and feature flags." msgstr "" #: ../../hypervisor_installation.rst:2286 @@ -2628,7 +2628,7 @@ msgstr "" #: ../../hypervisor_installation.rst:2331 # fa50c73129ea428e839debdffdc10099 -msgid "You must re-install VMware ESXi if you are going to re-use a host from a previous install." +msgid "You must re-install VMware ESXi if you are going to reuse a host from a previous install." msgstr "" #: ../../hypervisor_installation.rst:2336 @@ -3310,7 +3310,7 @@ msgstr "" #: ../../hypervisor_installation.rst:2754 # 7febd6557b3742e9a3d478672eba6cad -msgid "This is the IP address of the VSM appliance. This is the IP address you specify in the virtual switch IP Address field while configuting Nexus virtual switch." +msgid "This is the IP address of the VSM appliance. This is the IP address you specify in the virtual switch IP Address field while configuring Nexus virtual switch." msgstr "" #: ../../hypervisor_installation.rst:2758 @@ -3320,7 +3320,7 @@ msgstr "" #: ../../hypervisor_installation.rst:2756 # cab1502c5d5d4221873f13e86168b3d3 -msgid "Should be set to Enable.Always enable SSL. SSH is usually enabled by default during the VSM installation. However, check whether the SSH connection to the VSM is working, without which CloudStack failes to connect to the VSM." +msgid "Should be set to Enable.Always enable SSL. SSH is usually enabled by default during the VSM installation. However, check whether the SSH connection to the VSM is working, without which CloudStack fails to connect to the VSM." msgstr "" #: ../../hypervisor_installation.rst:2761 @@ -4196,7 +4196,7 @@ msgstr "" #: ../../hypervisor_installation.rst:3497 # 6e8937e78ff6442db35604533d058b4a -msgid "Next step is to update the Agent configuration setttings. The settings are in ``/etc/cloudstack/agent/agent.properties``" +msgid "Next step is to update the Agent configuration settings. The settings are in ``/etc/cloudstack/agent/agent.properties``" msgstr "" #: ../../hypervisor_installation.rst:3502 diff --git a/source/installguide/locale/pot/installation.pot b/source/installguide/locale/pot/installation.pot index e30f6448e1..a3ffcb6efe 100644 --- a/source/installguide/locale/pot/installation.pot +++ b/source/installguide/locale/pot/installation.pot @@ -495,7 +495,7 @@ msgstr "" #: ../../installation.rst:358 # d212ae279e594ea4a9b82dde3342f509 -msgid "Before setting up the Management Server, download vhd-util from `vhd-util `_." +msgid "Before setting up the Management Server, download vhd-util from `vhd-util `_." msgstr "" #: ../../installation.rst:361 @@ -1079,7 +1079,7 @@ msgstr "" #: ../../installation.rst:1085 # 60bd480d13124c16b4c8774b8abd5439 -msgid "Download vhd-util from `vhd-util `_" +msgid "Download vhd-util from `vhd-util `_" msgstr "" #: ../../installation.rst:1088 diff --git a/source/installguide/locale/pot/managing_networks.pot b/source/installguide/locale/pot/managing_networks.pot index cb2c581a83..821c40dc15 100644 --- a/source/installguide/locale/pot/managing_networks.pot +++ b/source/installguide/locale/pot/managing_networks.pot @@ -964,7 +964,7 @@ msgstr "" #: ../../managing_networks.rst:638 # 191010bd30424f3aa12cf309a48dcfc4 -msgid "You cannot apply IP Reservation if any VM is alloted with an IP address that is outside the Guest VM CIDR." +msgid "You cannot apply IP Reservation if any VM is allotted with an IP address that is outside the Guest VM CIDR." msgstr "" #: ../../managing_networks.rst:643 @@ -2761,12 +2761,12 @@ msgstr "" #: ../../managing_networks.rst:2392 # 596a2d14b50c4e298970de7db5c4d19b -msgid "Ensure that the endpointe.url parameter present in the Global Settings is set to the Management Server API URL. For example, http://10.102.102.22:8080/client/api. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server’s cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." +msgid "Ensure that the endpoint.url parameter present in the Global Settings is set to the Management Server API URL. For example, http://10.102.102.22:8080/client/api. In a multi-node Management Server deployment, use the virtual IP address configured in the load balancer for the management server’s cluster. Additionally, ensure that the NetScaler device has access to this IP address to provide AutoScale support." msgstr "" #: ../../managing_networks.rst:2400 # 59583fe0dfc14e2db8bcc23629da18e3 -msgid "If you update the endpointe.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see `Updating an AutoScale Configuration <#update-autoscale>`__" +msgid "If you update the endpoint.url, disable the AutoScale functionality of the load balancer rules in the system, then enable them back to reflect the changes. For more information see `Updating an AutoScale Configuration <#update-autoscale>`__" msgstr "" #: ../../managing_networks.rst:2407 @@ -5090,7 +5090,7 @@ msgstr "" #: ../../managing_networks.rst:4657 # 37506050acaf40fda04742118858f794 -msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly alloted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." +msgid "The administrator can deploy a set of VLANs and allow users to deploy VMs on these VLANs. A guest VLAN is randomly allotted to an account from a pre-specified set of guest VLANs. All the VMs of a certain tier of an account reside on the guest VLAN allotted to that account." msgstr "" #: ../../managing_networks.rst:4662 diff --git a/source/installguide/locale/pot/qig.pot b/source/installguide/locale/pot/qig.pot index d38faa0b42..8b94d471bd 100644 --- a/source/installguide/locale/pot/qig.pot +++ b/source/installguide/locale/pot/qig.pot @@ -442,12 +442,12 @@ msgstr "" #: ../../qig.rst:498 # 99f2fbc9c2454f3487ad43f84bb08a12 -msgid "In order to have live migration working libvirt has to listen for unsecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in /etc/libvirt/libvirtd.conf" +msgid "In order to have live migration working libvirt has to listen for insecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in /etc/libvirt/libvirtd.conf" msgstr "" #: ../../qig.rst:502 # 9fc492fb10044ee0844b1d25e91f50ee -msgid "Set the following paramaters:" +msgid "Set the following parameters:" msgstr "" #: ../../qig.rst:512 diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/building_from_source.po b/source/installguide/locale/zh_CN/LC_MESSAGES/building_from_source.po index ce68b1a7ff..f047dcc9b7 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/building_from_source.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/building_from_source.po @@ -296,7 +296,7 @@ msgid "" "While we have defined, and you have presumably already installed the " "bootstrap prerequisites, there are a number of build time prerequisites that" " need to be resolved. CloudStack uses maven for dependency resolution. You " -"can resolve the buildtime depdencies for CloudStack by running:" +"can resolve the buildtime dependencies for CloudStack by running:" msgstr "虽然我们做了一些定义，并且可能已经安装了引导的前提条件，但仍有一些在编译时需要解决的先决条件。CloudStack使用Maven进行依赖性解析。您可以通过运行以下命令，来解决编译CloudStack时的依赖性：" # 7e08137b290649cda9b8e9b728ff33aa @@ -561,10 +561,10 @@ msgstr "由于这些模块需要的依赖项不能和CloudStack一起发行， #: ../../building_from_source.rst:446 msgid "" "You may also need to download `vhd-util " -"`_, which was " +"`_, which was " "removed due to licensing issues. You'll copy vhd-util to the " "``scripts/vm/hypervisor/xenserver/`` directory." -msgstr "你可能还需要下载`vhd-util `_, 也是由于授权问题而被移除。 复制vhd-util到该目录： ``scripts/vm/hypervisor/xenserver/``." +msgstr "你可能还需要下载`vhd-util `_, 也是由于授权问题而被移除。 复制vhd-util到该目录： ``scripts/vm/hypervisor/xenserver/``." # bfbd7215ff0345f183a7946f620b1368 #: ../../building_from_source.rst:451 diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/configuration.po b/source/installguide/locale/zh_CN/LC_MESSAGES/configuration.po index eeba00e931..c9d8030831 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/configuration.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/configuration.po @@ -2161,7 +2161,7 @@ msgstr "" # febca3ed36dc41f0bfe48a3170c1b282 #: ../../configuration.rst:1264 msgid "" -"The createStoragePool API has been augmented to support plugable storage " +"The createStoragePool API has been augmented to support pluggable storage " "providers. The following is a list of parameters to use when adding storage " "to CloudStack that is based on the SolidFire plug-in:" msgstr "创建存储池的API已经被扩展到支持插件式存储供应商。下面给出了当向基于SolidFire插件的CloudStack添加存储时可使用的参数列表。" diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/kvm.po b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/kvm.po index e9cf577e45..abbaebaf6d 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/kvm.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/kvm.po @@ -95,7 +95,7 @@ msgstr "同一集群中主机必须使用相同版本的Linux系统。" # fc001eaf8fb842d7adbbf5bb977be8fd #: ../../hypervisor/kvm.rst:52 msgid "" -"All hosts within a cluster must be homogenous. The CPUs must be of the same " +"All hosts within a cluster must be homogeneous. The CPUs must be of the same " "type, count, and feature flags." msgstr "同一群集中的所有节点架构必须一致。CPU的型号、数量和功能参数必须相同。" @@ -383,7 +383,7 @@ msgstr "CloudStack使用libvirt管理虚拟机。因此正确地配置libvirt至 # ed8dd766459147cbb85ff50d90c4b80e #: ../../hypervisor/kvm.rst:243 msgid "" -"In order to have live migration working libvirt has to listen for unsecured " +"In order to have live migration working libvirt has to listen for insecured " "TCP connections. We also need to turn off libvirts attempt to use Multicast " "DNS advertising. Both of these settings are in " "``/etc/libvirt/libvirtd.conf``" @@ -862,7 +862,7 @@ msgstr "RHEL 及 CentOS使用iptables作为防火墙，执行以下iptables命 # f47cb1aac5b0422ea1409fd01b64e2db #: ../../hypervisor/kvm.rst:836 msgid "" -"These iptable settings are not persistent accross reboots, we have to save " +"These iptable settings are not persistent across reboots, we have to save " "them first." msgstr "这些iptables配置并不会持久保存，重启之后将会消失，我们必须手动保存这些配置。" diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/vsphere.po b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/vsphere.po index dd7d536ba0..314e650167 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/vsphere.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/vsphere.po @@ -101,7 +101,7 @@ msgstr "所有主机必须为64位架构并且支持HVM(启用Intel-VT或AMD-V) # 0a5dabc432dc454396baf7e656897fe6 #: ../../hypervisor/vsphere.rst:66 msgid "" -"All hosts within a cluster must be homogenous. That means the CPUs must be " +"All hosts within a cluster must be homogeneous. That means the CPUs must be " "of the same type, count, and feature flags." msgstr "同一群集中的所有节点必须为同一架构。CPU型号、数量和功能参数必须相同。" @@ -203,7 +203,7 @@ msgstr "必须配置vCenter使用443端口与CloudStack管理服务器通讯。" # 311e91fb341e4d30a649ba13d80e2e72 #: ../../hypervisor/vsphere.rst:114 msgid "" -"You must re-install VMware ESXi if you are going to re-use a host from a " +"You must re-install VMware ESXi if you are going to reuse a host from a " "previous install." msgstr "如果你计划利用之前安装的主机，那么必须重新安装VMware ESXi。" @@ -1042,7 +1042,7 @@ msgstr "" msgid "" "**Management IP Address** This is the IP address of the VSM appliance. This " "is the IP address you specify in the virtual switch IP Address field while " -"configuting Nexus virtual switch." +"configuring Nexus virtual switch." msgstr "" # 26a1722f2c004284958a7d40035272d8 @@ -1050,7 +1050,7 @@ msgstr "" msgid "" "**SSL** Should be set to Enable.Always enable SSL. SSH is usually enabled by" " default during the VSM installation. However, check whether the SSH " -"connection to the VSM is working, without which CloudStack failes to connect" +"connection to the VSM is working, without which CloudStack fails to connect" " to the VSM." msgstr "" diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/xenserver.po b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/xenserver.po index d87ecf4f31..fab9ab1dfd 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/xenserver.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor/xenserver.po @@ -73,7 +73,7 @@ msgstr "XenServer 6.2.0" # 5dee06ed5f2f472f9e0979ddbb241a63 #: ../../hypervisor/xenserver.rst:40 msgid "" -"You must re-install Citrix XenServer if you are going to re-use a host from " +"You must re-install Citrix XenServer if you are going to reuse a host from " "a previous install." msgstr "如果你想使用以前装的某台主机,你必须重新安装Citrix XenServer." @@ -302,10 +302,10 @@ msgstr "适用于XenServer 6.0.2：" # c7d858231a3142109c09bfcc3340078b #: ../../hypervisor/xenserver.rst:193 msgid "" -"`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" +msgstr "`http://download.cloudstack.org/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" # 2cbbc4bcdcdd42d0816a6b2df748a0d6 #: ../../hypervisor/xenserver.rst:196 @@ -315,9 +315,9 @@ msgstr "适用于XenServer 5.6 SP2:" # beac106ea20e420cae0ca5acb450646b #: ../../hypervisor/xenserver.rst:198 msgid "" -"`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz `_" +"`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz " +"`_" +msgstr "`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz `_" # 62cd9713906c45dc96254605c7134b11 #: ../../hypervisor/xenserver.rst:201 @@ -327,9 +327,9 @@ msgstr "适用于XenServer 6.0:" # 998fd323b14c42149cc6633f4df39b83 #: ../../hypervisor/xenserver.rst:203 msgid "" -"`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz `_" +"`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz " +"`_" +msgstr "`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz `_" # 50f6122c6c5e42dbb34f5942e788bd76 #: ../../hypervisor/xenserver.rst:207 diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor_installation.po b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor_installation.po index c31f471110..19d7b91ffe 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor_installation.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/hypervisor_installation.po @@ -108,7 +108,7 @@ msgstr "同一集群中主机必须使用相同版本的Linux系统。" # e392215de57d4843958e657b3d6d64c7 #: ../../hypervisor_installation.rst:70 ../../hypervisor_installation.rst:3366 msgid "" -"All hosts within a cluster must be homogenous. The CPUs must be of the same " +"All hosts within a cluster must be homogeneous. The CPUs must be of the same " "type, count, and feature flags." msgstr "同一群集中的所有节点架构必须一致。CPU的型号、数量和功能参数必须相同。" @@ -473,7 +473,7 @@ msgstr "CloudStack使用libvirt管理虚拟机。因此正确地配置libvirt至 #: ../../hypervisor_installation.rst:303 #: ../../hypervisor_installation.rst:3539 msgid "" -"In order to have live migration working libvirt has to listen for unsecured " +"In order to have live migration working libvirt has to listen for insecured " "TCP connections. We also need to turn off libvirts attempt to use Multicast " "DNS advertising. Both of these settings are in " "``/etc/libvirt/libvirtd.conf``" @@ -1082,7 +1082,7 @@ msgstr "RHEL 及 CentOS使用iptables作为防火墙，执行以下iptables命 #: ../../hypervisor_installation.rst:903 #: ../../hypervisor_installation.rst:3983 msgid "" -"These iptable settings are not persistent accross reboots, we have to save " +"These iptable settings are not persistent across reboots, we have to save " "them first." msgstr "这些iptables配置并不会持久保存，重启之后将会消失，我们必须手动保存这些配置。" @@ -1382,7 +1382,7 @@ msgstr "XenServer 6.2.0" # 7f67c993b17a4b25a8b436331132a38b #: ../../hypervisor_installation.rst:1022 msgid "" -"You must re-install Citrix XenServer if you are going to re-use a host from " +"You must re-install Citrix XenServer if you are going to reuse a host from " "a previous install." msgstr "如果你想使用以前装的某台主机,你必须重新安装Citrix XenServer." @@ -1565,10 +1565,10 @@ msgstr "适用于XenServer 6.0.2：" # 54880e3acb4945b4ae3d3fb251252130 #: ../../hypervisor_installation.rst:1181 msgid "" -"`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" +msgstr "`http://download.cloudstack.org/releases/3.0.1/XS-6.0.2/xenserver-cloud-supp.tgz `_" # 4405c659cea34cb2895c0f43693473f1 #: ../../hypervisor_installation.rst:1183 @@ -1578,9 +1578,9 @@ msgstr "适用于XenServer 5.6 SP2:" # b1533b01dec04d8ea37cb07d541d8013 #: ../../hypervisor_installation.rst:1185 msgid "" -"`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/2.2.0/xenserver-cloud-supp.tgz `_" +"`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz " +"`_" +msgstr "`http://download.cloudstack.org/releases/2.2.0/xenserver-cloud-supp.tgz `_" # 994df5c8945149b7b8663a2e603fc847 #: ../../hypervisor_installation.rst:1187 @@ -1590,9 +1590,9 @@ msgstr "适用于XenServer 6.0:" # bc80c4fa363248c292882b511d90808a #: ../../hypervisor_installation.rst:1189 msgid "" -"`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz " -"`_" -msgstr "`http://download.cloud.com/releases/3.0/xenserver-cloud-supp.tgz `_" +"`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz " +"`_" +msgstr "`http://download.cloudstack.org/releases/3.0/xenserver-cloud-supp.tgz `_" # 09db532336c943caa7e4713f7f57deaa #: ../../hypervisor_installation.rst:1193 @@ -3112,7 +3112,7 @@ msgstr "所有主机必须为64位架构并且支持HVM(启用Intel-VT或AMD-V) # 444698b909b14c1bafa79d28ca6d0e0c #: ../../hypervisor_installation.rst:2258 msgid "" -"All hosts within a cluster must be homogenous. That means the CPUs must be " +"All hosts within a cluster must be homogeneous. That means the CPUs must be " "of the same type, count, and feature flags." msgstr "同一群集中的所有节点必须为同一架构。CPU型号、数量和功能参数必须相同。" @@ -3184,7 +3184,7 @@ msgstr "必须配置vCenter使用443端口与CloudStack管理服务器通讯。" # fa50c73129ea428e839debdffdc10099 #: ../../hypervisor_installation.rst:2331 msgid "" -"You must re-install VMware ESXi if you are going to re-use a host from a " +"You must re-install VMware ESXi if you are going to reuse a host from a " "previous install." msgstr "如果你计划利用之前安装的主机，那么必须重新安装VMware ESXi。" @@ -4037,7 +4037,7 @@ msgstr "**管理 IP**" #: ../../hypervisor_installation.rst:2754 msgid "" "This is the IP address of the VSM appliance. This is the IP address you " -"specify in the virtual switch IP Address field while configuting Nexus " +"specify in the virtual switch IP Address field while configuring Nexus " "virtual switch." msgstr "VSM appliance的IP地址。 当配置Nexus虚拟交换机时在虚拟交换机的IP地址区域输入的IP地址。" @@ -4051,7 +4051,7 @@ msgstr "**SSL**" msgid "" "Should be set to Enable.Always enable SSL. SSH is usually enabled by default" " during the VSM installation. However, check whether the SSH connection to " -"the VSM is working, without which CloudStack failes to connect to the VSM." +"the VSM is working, without which CloudStack fails to connect to the VSM." msgstr "应该设置为启用。总是启用SSL。在VSM安装期间通常会启用SSH功能。尽管如此仍需检查是否能够使用SSH连接到VSM，如果不能无法连接，CloudStack到VSM的连接会失败。" # 747a5560bbed48598ec8fb9ad2739dde @@ -5144,7 +5144,7 @@ msgstr "CloudStack使用代理管理LXC实例。管理服务器与代理通信 # 6e8937e78ff6442db35604533d058b4a #: ../../hypervisor_installation.rst:3497 msgid "" -"Next step is to update the Agent configuration setttings. The settings are " +"Next step is to update the Agent configuration settings. The settings are " "in ``/etc/cloudstack/agent/agent.properties``" msgstr "接下来更新代理配置。在 ``/etc/cloudstack/agent/agent.properties`` 中配置" diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/installation.po b/source/installguide/locale/zh_CN/LC_MESSAGES/installation.po index 69875ad842..73debd3f29 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/installation.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/installation.po @@ -591,8 +591,8 @@ msgstr "这个步骤仅适用于安装了XenServer的hypervisor主机。" #: ../../installation.rst:358 msgid "" "Before setting up the Management Server, download vhd-util from `vhd-util " -"`_." -msgstr "在设置管理服务器前，下载 `vhd-util`_." +"`_." +msgstr "在设置管理服务器前，下载 `vhd-util`_." # d4c4d9a792ec46bbacc984b02fa8dd22 #: ../../installation.rst:361 @@ -1409,8 +1409,8 @@ msgstr "这个步骤仅适用于安装了XenServer的hypervisor主机。" #: ../../installation.rst:1085 msgid "" "Download vhd-util from `vhd-util " -"`_" -msgstr "下载 `vhd-util `_" +"`_" +msgstr "下载 `vhd-util `_" # 3b0ff1adaf804ec4b60b43307747e306 #: ../../installation.rst:1088 diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/managing_networks.po b/source/installguide/locale/zh_CN/LC_MESSAGES/managing_networks.po index 6bd38dd619..c32580f711 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/managing_networks.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/managing_networks.po @@ -1044,7 +1044,7 @@ msgstr "指定一个有效的客户虚拟机CIDR。只有不活动的IP在客户 # 191010bd30424f3aa12cf309a48dcfc4 #: ../../managing_networks.rst:638 msgid "" -"You cannot apply IP Reservation if any VM is alloted with an IP address that" +"You cannot apply IP Reservation if any VM is allotted with an IP address that" " is outside the Guest VM CIDR." msgstr "如果任一虚拟机被分配了客户虚拟机CIDR之外的IP地址时，IP预留将不能应用。" @@ -6365,7 +6365,7 @@ msgstr "主要的优势为：" #: ../../managing_networks.rst:4657 msgid "" "The administrator can deploy a set of VLANs and allow users to deploy VMs on" -" these VLANs. A guest VLAN is randomly alloted to an account from a pre-" +" these VLANs. A guest VLAN is randomly allotted to an account from a pre-" "specified set of guest VLANs. All the VMs of a certain tier of an account " "reside on the guest VLAN allotted to that account." msgstr "管理可以部署一个vlans集，同时运行用户部署虚拟机在这些vlan上。从预先指定的vlan集中随机的为租户分配一个来宾vlan.租户处于同一层的所有vm处于分配给这个租户的来宾vlan." diff --git a/source/installguide/locale/zh_CN/LC_MESSAGES/qig.po b/source/installguide/locale/zh_CN/LC_MESSAGES/qig.po index 5289ea229d..74d85d4c20 100644 --- a/source/installguide/locale/zh_CN/LC_MESSAGES/qig.po +++ b/source/installguide/locale/zh_CN/LC_MESSAGES/qig.po @@ -588,14 +588,14 @@ msgstr "CloudStack使用libvirt管理虚拟机。因此正确的配置libvirt至 # 99f2fbc9c2454f3487ad43f84bb08a12 #: ../../qig.rst:498 msgid "" -"In order to have live migration working libvirt has to listen for unsecured " +"In order to have live migration working libvirt has to listen for insecured " "TCP connections. We also need to turn off libvirts attempt to use Multicast " "DNS advertising. Both of these settings are in /etc/libvirt/libvirtd.conf" msgstr "为了实现动态迁移，libvirt需要监听使用非加密的TCP连接。还需要关闭libvirts尝试使用组播DNS进行广播。这些都是在 /etc/libvirt/libvirtd.conf文件中进行配置。" # 9fc492fb10044ee0844b1d25e91f50ee #: ../../qig.rst:502 -msgid "Set the following paramaters:" +msgid "Set the following parameters:" msgstr "设置下列参数：" # 95403c520e0647c88d0026cb30086615 diff --git a/source/installguide/management-server/_database.rst b/source/installguide/management-server/_database.rst index cc2d114113..c1eec4ef37 100644 --- a/source/installguide/management-server/_database.rst +++ b/source/installguide/management-server/_database.rst @@ -22,7 +22,7 @@ node, you can install the MySQL server locally. For an installation that has multiple management server nodes, we assume the MySQL database also runs on a separate node. -CloudStack has been tested with MySQL 5.1 and 5.5. These versions are +CloudStack has been tested with MySQL 8.0. These versions are included in RHEL/CentOS and Ubuntu. @@ -47,7 +47,7 @@ MySQL. See :ref:`install-database-on-separate-node`. .. parsed-literal:: - sudo apt-get install mysql-server + sudo apt install mysql-server #. Open the MySQL configuration file. The configuration file is ``/etc/my.cnf`` or ``/etc/mysql/my.cnf``, depending on your OS. @@ -64,20 +64,20 @@ MySQL. See :ref:`install-database-on-separate-node`. innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 - log-bin=mysql-bin - binlog-format = 'ROW' + log_bin=mysql-bin + binlog_format=ROW .. note:: - For Ubuntu 16.04 and later, make sure you specify a ``server-id`` in your ``.cnf`` file for binary logging. Set the ``server-id`` according to your database setup. + For Ubuntu 16.04 and later, make sure you specify a ``server_id`` in your ``/etc/mysql/mysql.conf.d/mysqld.cnf`` file for binary logging. Set the ``server_id`` according to your database setup. .. parsed-literal:: - server-id=source-01 + server_id=source-01 innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 - log-bin=mysql-bin - binlog-format = 'ROW' + log_bin=mysql-bin + binlog_format=ROW .. note:: You can also create a file ``/etc/mysql/conf.d/cloudstack.cnf`` @@ -166,11 +166,15 @@ MySQL. See :ref:`install-database-on-separate-node`. setenforce permissive +.. note:: In a production environment, selinux should be set to enforcing + and the necessary selinux policies are created to allow the + services to run. + #. Set up the database. The cloudstack-setup-databases script is used for creating the cloudstack - databases (cloud, cloud_usage), creating a user (cloud), granting permissions - to the user and preparing the tables for the first startup of the management + databases (cloud, cloud_usage), creating a User (cloud), granting permissions + to the User and preparing the tables for the first startup of the management server. The following command creates the "cloud" user on the database. @@ -190,15 +194,20 @@ MySQL. See :ref:`install-database-on-separate-node`. - In deploy-as, specify the username and password of the user deploying the database. In the following command, it is assumed - the root user is deploying the database and creating the "cloud" - user. + the root User is deploying the database and creating the "cloud" + User. + + - Since 4.21, the databases (cloud, cloud_usage) are only created if they + do not exist. This behavior prevents accidental recreation of existing + databases. The databases recreation can still be invoked by passing the + --force-recreate flag. - (Optional) There is an option to bypass the creating of the databases, - user and granting permissions to the user. This is useful if you don't + User and granting permissions to the user. This is useful if you don't want to expose your root credentials but still want the database to be prepared for first start up. These skipped steps will have had to be done manually prior to executing this script. This behaviour can be - envoked by passing the --schema-only flag. This flag conflicts with the + invoked by passing the --schema-only flag. This flag conflicts with the --deploy-as flag so the two cannot be used together. To set up the databases and user manually before executing the script with the flag, these commands can be executed: @@ -224,6 +233,10 @@ MySQL. See :ref:`install-database-on-separate-node`. GRANT process ON *.* TO cloud@`localhost`; GRANT process ON *.* TO cloud@`%`; + .. note:: + Since 4.21, it is required to pass the --force-recreate flag for + databases recreation. + - (Optional) For encryption\_type, use file or web to indicate the technique used to pass in the database encryption password. Default: file. See :ref:`about-password-key-encryption`. @@ -273,6 +286,20 @@ MySQL. See :ref:`install-database-on-separate-node`. done.” If the servlet container is Tomcat7 the argument --tomcat7 must be used. + .. note:: + Since 4.23.0, the ``cloudstack-setup-management`` command can download + System VM templates on demand when they are not present. + + Use the ``--systemvm-templates`` argument to specify which templates to + download. Valid values are ``all``, ``kvm-aarch64``, ``kvm-x86_64``, + ``xenserver``, and ``vmware``. A comma-separated list combining any of + these identifiers can also be supplied (for example + ``kvm-x86_64,xenserver``). If not specified, ``kvm-x86_64`` template + will be downloaded by default. + + For offline environments, provide a custom repository URL with the + ``--systemvm-templates-repository`` argument so the installer can fetch + templates from an internal mirror. .. _install-database-on-separate-node: @@ -305,7 +332,7 @@ same node for MySQL. See `“Install the Database on the Management Server Node .. parsed-literal:: - sudo apt-get install mysql-server + sudo apt install mysql-server #. Edit the MySQL configuration (/etc/my.cnf or /etc/mysql/my.cnf, depending on your OS) and insert the following lines in the [mysqld] @@ -324,9 +351,9 @@ same node for MySQL. See `“Install the Database on the Management Server Node innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=700 - log-bin=mysql-bin - binlog-format = 'ROW' - bind-address = 0.0.0.0 + log_bin=mysql-bin + binlog_format=ROW + bind-address=0.0.0.0 #. Start or restart MySQL to put the new configuration into effect. @@ -391,7 +418,7 @@ same node for MySQL. See `“Install the Database on the Management Server Node .. warning:: On CentOS 8 / SUSE, firewalld is the default firewall manager and controls iptables. It is recommended that it be disabled ``systemctl stop firewalld ; systemctl disable firewalld``, - since CloudStack directly manipulates the iptable rules to manage networks. + since CloudStack directly manipulates the iptable rules to manage Networks. .. warning:: On SUSE, iptables are not persisted on reboot, so it is recommended that iptables and @@ -430,7 +457,7 @@ The following command creates the cloud user on the database. want to expose your root credentials but still want the database to be prepared for first start up. These skipped steps will have had to be done manually prior to executing this script. This behaviour can be - envoked by passing the --schema-only flag. This flag conflicts with the + invoked by passing the --schema-only flag. This flag conflicts with the --deploy-as flag so the two cannot be used together. To set up the databases and user manually before executing the script with the flag, these commands can be executed: @@ -505,4 +532,18 @@ The following command creates the cloud user on the database. so ensure that the firewalld is disabled or ensure the correct firewalld rules are in place to allow traffic to ports 8080, 8250 and 9090 to the management server. + .. note:: + Since 4.23.0, the ``cloudstack-setup-management`` command can download + System VM templates on demand when they are not present. + + Use the ``--systemvm-templates`` argument to specify which templates to + download. Valid values are ``all``, ``kvm-aarch64``, ``kvm-x86_64``, + ``xenserver``, and ``vmware``. A comma-separated list combining any of + these identifiers can also be supplied (for example + ``kvm-x86_64,xenserver``). If not specified, ``kvm-x86_64`` template + will be downloaded by default. + + For offline environments, provide a custom repository URL with the + ``--systemvm-templates-repository`` argument so the installer can fetch + templates from an internal mirror. diff --git a/source/installguide/management-server/_nfs.rst b/source/installguide/management-server/_nfs.rst index e10c7719cf..f3ca1d899a 100644 --- a/source/installguide/management-server/_nfs.rst +++ b/source/installguide/management-server/_nfs.rst @@ -25,7 +25,7 @@ CloudStack. .. note:: NFS is not the only option for primary or secondary storage. For example, - you may use Ceph RBD, PowerFlex, GlusterFS, iSCSI, and others. The choice of storage + you may use Ceph RBD, PowerFlex, GlusterFS, iSCSI, Fiberchannel and others. The choice of storage system will depend on the choice of hypervisor and whether you are dealing with primary or secondary storage. @@ -54,7 +54,7 @@ from the Management Server. The exact commands for the following steps may vary depending on your operating system version. -The following steps asume you already have an NFS Server installed on your storage +The following steps assume you already have an NFS Server installed on your storage system. Please refer to the guide of your OS on how to install a NFS Server. .. warning:: @@ -132,7 +132,7 @@ operating system version. .. parsed-literal:: - apt-get install nfs-kernel-server + apt install nfs-kernel-server #. On the Management Server host, create two directories that you will use for primary and secondary storage. For example: @@ -186,7 +186,7 @@ operating system version. vi /etc/sysconfig/iptables Add the following lines at the beginning of the INPUT chain, where - is the network that you'll be using: + is the Network that you'll be using: .. parsed-literal:: @@ -253,8 +253,8 @@ operating system version. .. parsed-literal:: mkdir /primary - mount -t nfs :/export/primary + mount -t nfs :/export/primary /primary umount /primary mkdir /secondary - mount -t nfs :/export/secondary + mount -t nfs :/export/secondary /secondary umount /secondary diff --git a/source/installguide/management-server/_pkg_install.rst b/source/installguide/management-server/_pkg_install.rst index 9367e42dcb..716dda5b58 100644 --- a/source/installguide/management-server/_pkg_install.rst +++ b/source/installguide/management-server/_pkg_install.rst @@ -46,10 +46,10 @@ Install on SUSE zypper install cloudstack-management -Install on Ubuntu -^^^^^^^^^^^^^^^^^ +Install on Ubuntu/Debian +^^^^^^^^^^^^^^^^^^^^^^^^ .. parsed-literal:: - sudo apt-get install cloudstack-management + sudo apt install cloudstack-management diff --git a/source/installguide/management-server/_pkg_repo.rst b/source/installguide/management-server/_pkg_repo.rst index d4b48743a6..bc07f7973b 100644 --- a/source/installguide/management-server/_pkg_repo.rst +++ b/source/installguide/management-server/_pkg_repo.rst @@ -51,11 +51,13 @@ To add the CloudStack repository, create ``/etc/yum.repos.d/cloudstack.repo`` and insert the following information. +In the case of RHEL being used, you can replace 'centos' by 'rhel' in the value of baseurl + .. parsed-literal:: [cloudstack] name=cloudstack - baseurl=http://download.cloudstack.org/centos$releasever/|version|/ + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ enabled=1 gpgcheck=0 @@ -86,31 +88,61 @@ Now you should now be able to install CloudStack using zypper. DEB package repository ~~~~~~~~~~~~~~~~~~~~~~ +In Ubuntu: + You can add a DEB package repository to your apt sources with the following commands. Replace the code name with your Ubuntu LTS version : -Ubuntu 16.04 (Xenial), Ubuntu 18.04 (Bionic) and Ubuntu 20.04 (Focal) . -Ubuntu 14.04 (Trusty) is no longer supported. +Ubuntu 22.04 (Jammy), and Ubuntu 24.04 (Noble). +Ubuntu 12.04 (Precise), Ubuntu 14.04 (Trusty), Ubuntu 16.04 (Xenial), Ubuntu 18.04 (Bionic), +and Ubuntu 20.04 (Focal) are no longer supported. Use your preferred editor and open (or create) ``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided -repository to the file (replace "trusty" with "xenial" or "bionic" if it is the case): +repository to the file (replace "noble" with "jammy" or "focal" or "bionic" if it is the case): .. parsed-literal:: - deb http://download.cloudstack.org/ubuntu focal |version| + deb https://download.cloudstack.org/ubuntu noble |version| We now have to add the public key to the trusted keys. .. parsed-literal:: - wget -O - http://download.cloudstack.org/release.asc |sudo apt-key add - + wget -O - https://download.cloudstack.org/release.asc |sudo tee /etc/apt/trusted.gpg.d/cloudstack.asc Now update your local apt cache. .. parsed-literal:: - sudo apt-get update + sudo apt update Your DEB package repository should now be configured and ready for use. +In Debian: + +You can also install CloudStack on Debian systems using APT in the same way +as on Ubuntu. Replace the Debian release codename (for example, "bookworm" +for Debian 12) as appropriate. + +Use your preferred editor and open (or create) +``/etc/apt/sources.list.d/cloudstack.list``. Add the community provided +repository to the file (replace "bookworm" with the codename of Debian release if it is the case): + +.. parsed-literal:: + + deb https://download.cloudstack.org/debian bookworm |version| + +We now have to add the public key to the trusted keys. + +.. parsed-literal:: + + wget -O - https://download.cloudstack.org/release.asc |sudo tee /etc/apt/trusted.gpg.d/cloudstack.asc + +Now update your local apt cache. + +.. parsed-literal:: + + sudo apt update + +Your DEB package repository should now be configured and ready for use. diff --git a/source/installguide/management-server/_prerequisite.rst b/source/installguide/management-server/_prerequisite.rst index c3b1324aa9..e932c2c603 100644 --- a/source/installguide/management-server/_prerequisite.rst +++ b/source/installguide/management-server/_prerequisite.rst @@ -91,7 +91,7 @@ node. .. parsed-literal:: - $ apt-get install chrony + $ apt install chrony In SUSE: @@ -103,7 +103,7 @@ node. will be installed. .. warning:: - CloudStack |version| requires Java 11 JRE. Installing CloudStack packages will - automatically install Java 11, but it's good to explicitly confirm that the Java 11 + CloudStack |version| requires Java 17 JRE. Installing CloudStack packages will + automatically install Java 17, but it's good to explicitly confirm that the Java 17 is the selected/active one (in case you had a previous Java version already installed) with ``alternatives --config java`` after CloudStack packages are already installed. diff --git a/source/installguide/management-server/_systemvm.rst b/source/installguide/management-server/_systemvm.rst index 0393768dde..0e6f2433cf 100644 --- a/source/installguide/management-server/_systemvm.rst +++ b/source/installguide/management-server/_systemvm.rst @@ -16,11 +16,10 @@ Prepare the System VM Template ------------------------------ -From Apache CloudStack v4.16 onwards, upgrade path handles systemVM template registration, if not done prior to initiating upgrade. -One may choose, to also omit the systemVM template seeding step during fresh installation of CloudStack, as support has been added to -initiate systemVM template registration for all hypervisors present in the zone when the first secondary storage pool is added. -Secondary storage must be seeded with a template that is used for -CloudStack system VMs. +From Apache CloudStack v4.16 onwards, upgrade path handles SystemVM Template registration, if not done prior to initiating upgrade. +One may choose, to also omit the SystemVM Template seeding step during fresh installation of CloudStack, as support has been added to +initiate SystemVM Template registration for all hypervisors present in the zone when the first secondary storage pool is added. +Secondary storage must be seeded with a Template that is used for CloudStack System VMs. .. note:: When copying and pasting a command, be sure the command has pasted as a @@ -29,8 +28,8 @@ CloudStack system VMs. #. On the Management Server, run one or more of the following ``cloud-install-sys-tmplt`` commands to retrieve and decompress the - system VM template. Run the command for each hypervisor type that you - expect end users to run in this Zone. + System VM Template. Run the command for each hypervisor type that you + expect end Users to run in this Zone. If your secondary storage mount point is not named ``/mnt/secondary``, substitute your own mount point name. diff --git a/source/installguide/management-server/index.rst b/source/installguide/management-server/index.rst index c6a2532b4c..2efe51a7f8 100644 --- a/source/installguide/management-server/index.rst +++ b/source/installguide/management-server/index.rst @@ -49,7 +49,7 @@ What should you do next? CloudStack on an ongoing basis. See Log In to the UI. - When you're ready, add the cloud infrastructure and try running some - virtual machines on it, so you can watch how CloudStack manages the + Instances on it, so you can watch how CloudStack manages the infrastructure. See Provision Your Cloud Infrastructure. diff --git a/source/installguide/optional_installation.rst b/source/installguide/optional_installation.rst index 54cd52dab2..d9dee1b85f 100644 --- a/source/installguide/optional_installation.rst +++ b/source/installguide/optional_installation.rst @@ -26,7 +26,7 @@ Installing the Usage Server (Optional) You can optionally install the Usage Server once the Management Server is configured properly. The Usage Server takes data from the events in -the system and enables usage-based billing for accounts. +the system and enables usage-based billing for Accounts. When multiple Management Servers are present, the Usage Server may be installed on any number of them. The Usage Servers will coordinate usage @@ -48,7 +48,7 @@ Steps to Install the Usage Server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Package repository should already being configured. Refer to - `Configure Package Repository `_ + `Configure Package Repository <../installguide/management-server/_pkg_repo.html#configure-package-repository>`_ #. Install package cloudstack-usage @@ -62,7 +62,7 @@ Steps to Install the Usage Server .. parsed-literal:: - # apt-get install cloudstack-usage + # apt install cloudstack-usage #. Once installed, start the Usage Server with the following command. @@ -114,6 +114,39 @@ For storing certificates, admins can create and configure a java keystore file and configure the same in the server.properties file as illustrated above. +Health Checks and Monitoring (Optional) +--------------------------------------- + +CloudStack has a plugin for exporting metrics in the format that Prometheus can consume. +This is done by enabling the following configuration parameters in the Global Settings. + + .. parsed-literal:: + + # cloudmonkey update configuration name=prometheus.exporter.enable value=true + # cloudmonkey update configuration name=prometheus.exporter.port value=9595 + # cloudmonkey update configuration name=prometheus.exporter.allowed.ips value="127.0.0.1,192.168.0.10" + +.. note:: + These settings are available to be configured via the CloudStack UI as well. + CloudStack Management needs to be restarted for the changes to take effect. + Replace the mock IP address 192.168.0.10 with the actual IP address of the Prometheus server. + +.. warning:: + A list of addresses can be provided as a comma separated list. It does NOT accept CIDR notation. + +Then, configure prometheus to start pulling metrics by adding the following configuration to ``/etc/prometheus/prometheus.yml``. + + .. parsed-literal:: + + - job_name: 'management' + static_configs: + - targets: ['192.168.0.20:9595'] + +.. note:: + Replace the mock IP address 192.168.0.20 with the actual IP address of the Management server. + Public dashboards are available in the Grafana repository for visualizing CloudStack Management metrics. + + Database Replication (Optional) ------------------------------- @@ -158,9 +191,9 @@ steps are a guide to implementing MySQL replication. # service mysql restart -#. Create a replication account on the source server and give it privileges. We +#. Create a replication Account on the source server and give it privileges. We will use the "cloud-repl" user with the password "password". This - assumes that source and replica run on the 172.16.1.0/24 network. + assumes that source and replica run on the 172.16.1.0/24 Network. .. sourcecode: bash .. parsed-literal:: @@ -186,7 +219,7 @@ steps are a guide to implementing MySQL replication. | mysql-bin.000001 | 412 | | | +------------------+----------+--------------+------------------+ -#. Note the file and the position that are returned by your instance. +#. Note the file and the position that are returned by your Instance. #. Exit from this session. @@ -287,7 +320,7 @@ Amazon Web Services Compatible Interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CloudStack can translate Amazon Web Services (AWS) API calls to native -CloudStack API calls so that users can continue using existing +CloudStack API calls so that Users can continue using existing AWS-compatible tools. This translation service runs as a separate web application in the same tomcat server as the management server of CloudStack, listening on a different port. The Amazon Web Services (AWS) @@ -314,7 +347,7 @@ Limitations - Features such as Elastic IP (EIP) and Elastic Load Balancing (ELB) are only available in an infrastructure with a Citrix NetScaler device. Users accessing a Zone with a NetScaler device will need to - use a NetScaler-enabled network offering (DefaultSharedNetscalerEIP + use a NetScaler-enabled Network offering (DefaultSharedNetscalerEIP and ELBNetworkOffering). @@ -371,7 +404,7 @@ You do not have to enable both at the same time. Enable the ones you need. This can be done via the CloudStack GUI by going in *Global Settings* or via the API. -The snapshot below shows you how to use the GUI to enable these services +The Snapshot below shows you how to use the GUI to enable these services |Use the GUI to set the configuration variable to true| @@ -397,7 +430,7 @@ types `_ API names (e.g m1.small,m1.large). This can be done via the CloudStack GUI. Go under *Service Offerings* select *Compute offering* and either create a new compute offering or modify an existing one, ensuring that the name -matches an EC2 instance type API name. The snapshot below shows you how: +matches an EC2 instance type API name. The Snapshot below shows you how: |Use the GUI to set the name of a compute service offering to an EC2 instance type API name.| @@ -427,16 +460,16 @@ and if need be update the port. AWS API User Setup ~~~~~~~~~~~~~~~~~~ -In general, users need not be aware that they are using a translation +In general, Users need not be aware that they are using a translation service provided by CloudStack. They only need to send AWS API calls to CloudStack's endpoint, and it will translate the calls to the native CloudStack API. Users of the Amazon EC2 compatible interface will be able to keep their existing EC2 tools and scripts and use them with their CloudStack deployment, by specifying the endpoint of the -management server and using the proper user credentials. In order to do -this, each user must perform the following configuration steps: +management server and using the proper User credentials. In order to do +this, each User must perform the following configuration steps: -- Generate user credentials. +- Generate User credentials. - Register with the service. @@ -447,7 +480,7 @@ this, each user must perform the following configuration steps: AWS API Command-Line Tools Setup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To use the EC2 command-line tools, the user must perform these steps: +To use the EC2 command-line tools, the User must perform these steps: #. Be sure you have the right version of EC2 Tools. The supported version is available at @@ -507,7 +540,7 @@ differences between the CloudStack and Amazon EC2 versions, and these differences are noted. The underlying SOAP call for each command is also given, for those who have built tools using those calls. -Table 1. Elastic IP API mapping +Table 1. Elastic IP API mapping .. cssclass:: table-striped table-bordered table-hover @@ -527,7 +560,7 @@ Table 1. Elastic IP API mapping | -Table 2. Availability Zone API mapping +Table 2. Availability Zone API mapping .. cssclass:: table-striped table-bordered table-hover @@ -539,7 +572,7 @@ Table 2. Availability Zone API mapping | -Table 3. Images API mapping +Table 3. Images API mapping .. cssclass:: table-striped table-bordered table-hover @@ -557,7 +590,7 @@ Table 3. Images API mapping | -Table 4. Image Attributes API mapping +Table 4. Image Attributes API mapping .. cssclass:: table-striped table-bordered table-hover @@ -573,7 +606,7 @@ Table 4. Image Attributes API mapping | -Table 5. Instances API mapping +Table 5. Instances API mapping .. cssclass:: table-striped table-bordered table-hover @@ -595,7 +628,7 @@ Table 5. Instances API mapping | -Table 6. Instance Attributes Mapping +Table 6. Instance Attributes Mapping .. cssclass:: table-striped table-bordered table-hover @@ -607,7 +640,7 @@ Table 6. Instance Attributes Mapping | -Table 7. Keys Pairs Mapping +Table 7. Keys Pairs Mapping .. cssclass:: table-striped table-bordered table-hover @@ -625,7 +658,7 @@ Table 7. Keys Pairs Mapping | -Table 8. Passwords API Mapping +Table 8. Passwords API Mapping .. cssclass:: table-striped table-bordered table-hover @@ -637,7 +670,7 @@ Table 8. Passwords API Mapping | -Table 9. Security Groups API Mapping +Table 9. Security Groups API Mapping .. cssclass:: table-striped table-bordered table-hover @@ -657,7 +690,7 @@ Table 9. Security Groups API Mapping | -Table 10. Snapshots API Mapping +Table 10. Snapshots API Mapping .. cssclass:: table-striped table-bordered table-hover @@ -673,7 +706,7 @@ Table 10. Snapshots API Mapping | -Table 11. Volumes API Mapping +Table 11. Volumes API Mapping .. cssclass:: table-striped table-bordered table-hover @@ -713,7 +746,7 @@ AWS API Interface. First is an EC2 example. Replace the Access and Secret Keys with your own and update the endpoint. -Example 1. An EC2 Boto example +Example 1. An EC2 Boto example .. sourcecode:: python @@ -753,7 +786,7 @@ Example 1. An EC2 Boto example Second is an S3 example. The S3 interface in CloudStack is obsolete. If you need an S3 interface you should look at systems like RiakCS, Ceph or GlusterFS. This example is here for completeness and can be adapted to other S3 endpoint. -Example 2. An S3 Boto Example +Example 2. An S3 Boto Example .. sourcecode:: python diff --git a/source/installguide/overview/_overview.rst b/source/installguide/overview/_overview.rst index 3ba81aff0e..376cbc1481 100644 --- a/source/installguide/overview/_overview.rst +++ b/source/installguide/overview/_overview.rst @@ -23,7 +23,7 @@ For those who have already gone through a design phase and planned a more sophisticated deployment, or those who are ready to start scaling up a trial installation. With the following procedures, you can start using the more powerful features of CloudStack, such as advanced VLAN -networking, high availability, additional network elements such as load +networking, high availability, additional Network elements such as load balancers and firewalls, and support for multiple hypervisors including Citrix XenServer, KVM, and VMware vSphere. diff --git a/source/installguide/overview/_requirements.rst b/source/installguide/overview/_requirements.rst index 173e32908f..7d42d6f70d 100644 --- a/source/installguide/overview/_requirements.rst +++ b/source/installguide/overview/_requirements.rst @@ -25,11 +25,11 @@ Management Server, Database, and Storage System Requirements The machines that will run the Management Server and MySQL database must meet the following requirements. The same machines can also be used to provide primary and secondary storage, such as via localdisk or NFS. The -Management Server may be placed on a virtual machine. +Management Server may be placed on an Instance. - Operating system: - - Preferred: CentOS/RHEL 7.2+ or Ubuntu 16.04(.2) or higher + - Preferred: EL8+ or Ubuntu 22.04 or higher - 64-bit x86 CPU (more cores results in better performance) diff --git a/source/plugins/cloudian-connector.rst b/source/plugins/cloudian-connector.rst index 58bb170a90..bfe1db3571 100644 --- a/source/plugins/cloudian-connector.rst +++ b/source/plugins/cloudian-connector.rst @@ -26,10 +26,10 @@ Connector integrates Cloudian S3 Storage into the CloudStack Management GUI and allows administrators to easily give their CloudStack users access to and manage their own S3 storage areas. -Compatibilty -~~~~~~~~~~~~ +Compatibility +~~~~~~~~~~~~~ -The following table shows the compatiblity of Cloudian Connector with CloudStack. +The following table shows the compatibility of Cloudian Connector with CloudStack. .. cssclass:: table-striped table-bordered table-hover @@ -81,10 +81,10 @@ logged in. User Mapping and Provisioning/De-provisioning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CloudStack domains are mapped to Cloudian Groups. CloudStack accounts within +CloudStack domains are mapped to Cloudian Groups. CloudStack Accounts within those domains are mapped to Cloudian users. The Cloudian user and group are created on demand if it doesn’t already exist when the CloudStack user accesses -CMC through the Cloudian Storage button. When accounts and domains are created +CMC through the Cloudian Storage button. When Accounts and domains are created or removed in CloudStack, they automatically create or remove users or groups in CMC. @@ -156,7 +156,15 @@ Cloudian ships with SSO disabled by default. You will need to enable it on each CMC server. Additionally, you will need to choose a unique SSO shared key that you will also configure in the CloudStack connector further below. -Edit Puppet config to enable SSO on all CMC servers: +HyperStore 8+ instructions to enable SSO on all CMC servers: + + :: + + # hsctl config set cmc.sso.enabled=true + # hsctl config set cmc.sso.sharedKey=YourSecretKeyHere + # hsctl config apply cmc + +Older HyperStore versions use Puppet. Edit Puppet config to enable SSO on all CMC servers: :: @@ -166,7 +174,7 @@ Edit Puppet config to enable SSO on all CMC servers: .. note:: - Once configured in Puppet, you should roll out out to each CMC server and + Once configured in Puppet, you should roll out to each CMC server and restart CMC services. Please refer to the HyperStore documentation for how to do this. @@ -229,8 +237,7 @@ settings. To enable the connector, ensure that the global setting "cloudian.connector.enabled" is set to true. Finally, restart each of the management server(s) to reload and enable the connector. -For example, here is how you can restart the CloudStack management server -installed on CentOS7: +For example, here is how you can restart the CloudStack management server: :: @@ -316,13 +323,13 @@ directly to S3 but instead talk through the standard file system API. As such, CloudStack requires an NFS staging server which the Hypervisors use to read and write data from/to. The NFS storage requirements for the staging server are small however as space is only required while objects are staged (moving) -between the S3 server and the VMs. +between the S3 server and the Instances. DNS Name Resolution Requirement ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -All CloudStack Management Servers, system VMs and customer VMs (if required) +All CloudStack Management Servers, System VMs and customer Instances (if required) must be able to resolve your S3 bucket names. Usually, if you already have Cloudian installed and running in your environment, this is already working. At a minimum the following names should resolve to the correct IP addresses @@ -348,7 +355,7 @@ Adding Cloudian as CloudStack Secondary Storage Setup a Cloudian User and Bucket for Secondary Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -S3 Secondary Storage stores the CloudStack templates, snapshots etc in a +S3 Secondary Storage stores the CloudStack Templates, Snapshots etc in a dedicated S3 Bucket. To properly configure CloudStack you will need to know the S3 Bucket name and how to access your S3 Server (the S3 endpoint, access key and secret key). @@ -379,9 +386,9 @@ Create a dedicated bucket: Open Up Access to your S3 Network from Secondary Storage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your S3 server is on a different network to your Secondary Storage VM, you -will need to open up access to the S3 network. This also allows users to -download templates from their S3 object store areas. +If your S3 server is on a different Network to your Secondary Storage VM, you +will need to open up access to the S3 Network. This also allows users to +download Templates from their S3 object store areas. .. figure:: /_static/images/cloudian-ss_globalopt.png :align: center @@ -450,13 +457,13 @@ Adding S3 Secondary Storage: When you have finished adding Cloudian as Secondary Storage in the previous steps, CloudStack will populate the new secondary storage with the system and -default templates. This can take some time do download as the templates are +default Templates. This can take some time do download as the Templates are quite big. .. note:: - You can check if the system template and the default template have properly + You can check if the system Template and the default Template have properly downloaded to the new secondary storage by navigating to Templates, selecting a - template, clicking on the Zones tab and checking its Status is Ready 100% + Template, clicking on the Zones tab and checking its Status is Ready 100% Downloaded. .. note:: diff --git a/source/plugins/cloudstack-csi-driver.rst b/source/plugins/cloudstack-csi-driver.rst new file mode 100644 index 0000000000..25f1cd9b58 --- /dev/null +++ b/source/plugins/cloudstack-csi-driver.rst @@ -0,0 +1,57 @@ +.. 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 CSI Driver +======================= + +CloudStack Container Storage Interface (CSI) plugin enables Kubernetes clusters running on Apache CloudStack to dynamically provision, manage, and use CloudStack storage volumes + +Features +-------- + +- Automatic provisioning: Create persistent volumes on-demand from Kubernetes PVCs +- No manual intervention: Eliminates need to manually create CloudStack volumes +- Kubernetes-native: Uses standard Kubernetes storage classes and PVC workflows + +Advanced Storage Features +------------------------- +- Volume snapshots: Backup and restore capabilities +- Dynamic expansion: Grow volumes without downtime or data migration +- Flexible reclaim policies: Choose between automatic cleanup or data retention + +Core Components +----------------- +- CSI Controller: Manages volume lifecycle, snapshots, and CloudStack API interactions +- CSI Node Driver: Handles volume mounting and unmounting on worker nodes +- Storage Class Syncer: Automatically syncs CloudStack disk offerings to Kubernetes storage classes + +CSI integration with CKS +~~~~~~~~~~~~~~~~~~~~~~~~~~ +From 4.22.0, CloudStack Kubernetes Service provides CSI integration that allows dynamic provisioning of CloudStack volumes for Kubernetes pods running on CKS clusters. +To enable CSI integration, the CKS data ISOs must have the CSI manifests. Rebuilding the CKS data ISOs using the `create-kubernetes-binaries-iso.sh` script will build ISOs with CSI manifests and images. Pre-built ISOs for Kubernetes versions 1.31.1, 1.32.5 and 1.33.1 are available at https://download.cloudstack.org/cks/ + +|cks-csi-integration.png| + +Enabling CSI integration for a CKS cluster can be done by selecting the `Enable CSI Integration` checkbox in the Advanced Settings section of the Kubernetes cluster creation form. +Doing so will setup the CSI components - the CSI controller and the CSI node daemonset - on the cluster during its creation. + +|cks-csi-pods.png| + +Further details about using CSI with CKS can be found at: https://github.com/cloudstack/cloudstack-csi-driver/blob/main/README.md + +.. |cks-csi-integration.png| image:: /_static/images/cks-csi-integration.png + :alt: Integration of CSI with CKS. +.. |cks-csi-pods.png| image:: /_static/images/cks-csi-pods.png + :alt: CSI Pods. \ No newline at end of file diff --git a/source/plugins/cloudstack-kubernetes-provider.rst b/source/plugins/cloudstack-kubernetes-provider.rst index 910979c5df..d8a568f215 100644 --- a/source/plugins/cloudstack-kubernetes-provider.rst +++ b/source/plugins/cloudstack-kubernetes-provider.rst @@ -34,11 +34,11 @@ The Prebuilt containers are available on `Docker Hub 443/TCP 5d1h + nginx-deployment2 NodePort 10.103.111.85 80:32014/TCP 4s + + 2. Navigate to network and acquire a public IP. + + |cks-acquire-publicip.png| + + 3. Add a firewall rule on port 80 on the public IP address + + |cks-addfirewall.png| + + 4. Add a loadbalancer rule mentioning the private node port and add the corresponding kubernetes worker node. + + |cks-addloadbalancer.png| + + |cks-addnode.png| + .. |ckp-ip.png| image:: /_static/images/ckp-ip.png .. |ckp-ip-fw.png| image:: /_static/images/ckp-ip-fw.png .. |ckp-ip-lb.png| image:: /_static/images/ckp-ip-lb.png +.. |cks-acquire-publicip.png| image:: /_static/images/cks-acquire-publicip.png +.. |cks-addfirewall.png| image:: /_static/images/cks-addfirewall.png +.. |cks-addloadbalancer.png| image:: /_static/images/cks-addloadbalancer.png +.. |cks-addnode.png| image:: /_static/images/cks-addnode.png \ No newline at end of file diff --git a/source/plugins/cloudstack-kubernetes-service.rst b/source/plugins/cloudstack-kubernetes-service.rst index ad76c6d3c0..12921f30f2 100644 --- a/source/plugins/cloudstack-kubernetes-service.rst +++ b/source/plugins/cloudstack-kubernetes-service.rst @@ -13,16 +13,28 @@ 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. +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. Also the global setting "endpoint.url" needs to be set to the CloudStack management server ip example (http://management-server-ip:8080/client/api) -With CoreOS having reached EOL, from 4.16 the Kubernetes Service Plugin will use the existing SystemVM template for deploying kubernetes clusters. For installation of Kubernetes binaries on the 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. +The Kubernetes Service plugin will use the existing SystemVM Template by default for deploying Kubernetes clusters. For +installation of Kubernetes binaries on the 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, control 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/. +.. note:: + From version 4.21.0, users can choose different templates and service offerings for different types of nodes (worker, control, etcd nodes) for deploying Kubernetes clusters. The templates must be previously registered selecting the 'For CKS' option. + See :ref:`flexible-kubernetes-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 Instances. Under the hood, control 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/. + +Calico CNI provider plugin is used for cluster networking supported from ACS 4.21 onwards. More about Calico CNI plugin here: https://docs.projectcalico.org/getting-started/kubernetes/. 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. +From ACS 4.19 onwards, you can also create `ExternalManaged` kubernetes clusters using the API. This helps provide a centralized view of kubernetes clusters managed by other providers. + Enabling the Kubernetes Service -------------------------------- @@ -43,6 +55,8 @@ Once the Kubernetes service is running the new APIs will become accessible and t **NOTE:** From ACS 4.16 onwards, if a CKS cluster is to be deployed on VMware, the 'vmware.create.full.clone' configuration parameter will need to be set to true, so as to allow resizing of root volumes of the cluster nodes. +.. _kubernetes-supported-versions: + Kubernetes Supported Versions ------------------------------ @@ -51,24 +65,51 @@ The Kubernetes service provides the functionality to manage multiple supported K - 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 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 Instances 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. +Eg: To generate the latest kubernetes iso + +.. parsed-literal:: + + 1.33.1, kubernetes version, see https://github.com/kubernetes/kubernetes/releases + 1.7.1, CNI version, see https://github.com/containernetworking/plugins/releases + 1.33.0, cri-tools version, see https://github.com/kubernetes-sigs/cri-tools/releases + 3.30.0, calico addon for kubernetes, see https://raw.githubusercontent.com/projectcalico/calico/v3.30.0/manifests/calico.yaml + 2.7.0, kubernetes dashboard version, see https://github.com/kubernetes/dashboard/release + Usage: .. parsed-literal:: - # ./create-kubernetes-binaries-iso.sh OUTPUT_PATH KUBERNETES_VERSION CNI_VERSION CRICTL_VERSION WEAVENET_NETWORK_YAML_CONFIG DASHBOARD_YAML_CONFIG + # ./create-kubernetes-binaries-iso.sh OUTPUT_PATH KUBERNETES_VERSION CNI_VERSION CRICTL_VERSION CALICO_NETWORK_YAML_CONFIG DASHBOARD_YAML_CONFIG [OPTIONAL_OUTPUT_FILENAME] [OPTIONAL_ETCD_VERSION] -Eg: + + +Eg: To generate the kubernetes iso with calico cni plugin .. parsed-literal:: + + # ./create-kubernetes-binaries-iso.sh ./ 1.33.1 1.7.1 1.33.0 https://raw.githubusercontent.com/projectcalico/calico/v3.30.0/manifests/calico.yaml https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml setup-v1.33.1-calico + +Eg: To generate the kubernetes iso with calico cni plugin for ARM64 architecture add aarch64 as the last parameter. - # ./create-kubernetes-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 +.. parsed-literal:: + + # ./create-kubernetes-binaries-iso.sh ./ 1.33.1 1.7.1 1.33.0 https://raw.githubusercontent.com/projectcalico/calico/v3.30.0/manifests/calico.yaml https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml aarch64 setup-v1.33.1-calico-arm64 **NOTE:** -From ACS 4.16 onwards, Kubernetes versions >= 1.20.x are only supported (https://endoflife.date/kubernetes). +From ACS 4.21 onwards, it is possible to specify the version for etcd binaries in the create-kubernetes-binaries-iso.sh script as an optional parameter - ETCD_VERSION. When the ETCD_VERSION parameter is set, the specified etcd version binaries are downloaded and stored in the Kubernetes ISO. + +Example for etcd version 3.5.1: + +.. parsed-literal:: + + # ./create-kubernetes-binaries-iso.sh ./ 1.33.1 1.7.1 1.33.0 https://raw.githubusercontent.com/projectcalico/calico/v3.30.0/manifests/calico.yaml https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml setup-v1.33.1-calico-etcd 3.5.1 + +To deploy Kubernetes clusters with +Kubernetes ISOs built with a specified etcd version are necessary for creating Kubernetes clusters with separate etcd nodes. See :ref:`flexible-kubernetes-clusters`. Working with Kubernetes supported version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,6 +121,10 @@ Once the ISO has been built for a desired Kubernetes version, it can be added by |cks-add-version-form.png| +.. note:: + From 4.21.0, it is possible to deploy separate dedicated etcd nodes. This requires + the Kubernetes ISO contains the etcd binaries. + 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) @@ -92,15 +137,15 @@ addKubernetesSupportedVersion API can be used by an admin to add a new supported 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 + > add kubernetessupportedversion name=v1.33.1 semanticversion=1.33.1 url=http://172.20.0.1/files/setup-1.33.1.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", + "isoname": "v1.33.1-Kubernetes-Binaries-ISO", "isostate": "Active", - "semanticversion": "1.13.2", - "name": "v1.13.2", + "semanticversion": "1.33.1", + "name": "v1.33.1", "supportsha": false, "zoneid": "34d23dd5-5ced-4e8b-9b0a-835a0b8ae2a6", "zonename": "KVM-advzone1" @@ -109,7 +154,7 @@ For example: } } -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 ###################################### @@ -137,21 +182,38 @@ deleteKubernetesSupportedVersion API has been provided for admins to delete an e 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 corresponding to the provided 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 up or down based on the number of worker nodes provided and to the service offering used by each node. +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 Instances as per cluster size using the binaries corresponding to the provided 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 up or down based on the number of worker nodes provided and to 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. The default network offering must be set in the Global Settings for the service to create Kubernetes clusters. +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 Instances on the cluster. The default Network offering must be set in the Global Settings for the service to create Kubernetes clusters. -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: +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 +A new Network offering named DefaultNetworkOfferingforKubernetesService has been added since 4.14.0 .. note:: - Multi-control nodes, HA cluster can be created for Kubernetes version 1.16 and above only. - - While creating multi-control nodes, 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 control nodes. Over the CloudStack isolated network these rules are automatically provisioned. + - While creating multi-control nodes, 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 control nodes. Over the CloudStack isolated Network these rules are automatically provisioned. + + +Examples of how to ssh into the Control and Worker nodes + +Control node + +.. parsed-literal:: + + ssh -i -p 2222 cloud@ + +Worker node + +.. parsed-literal:: + + ssh -i -p 2223 cloud@ + + Managing Kubernetes clusters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,25 +227,45 @@ New Kubernetes clusters can be created using the API or via the UI. User will be |cks-create-cluster-form.png| +From 4.21.0, you can select the hypervisor type for Kubernetes cluster nodes. By default, no hypervisor is selected. + +From 4.21.0, users will be provided with an optional section displayed on toggling the 'Show Advanced Settings' button. In this section, users can select templates and service offerings for: +- Worker nodes +- Control nodes +- Etcd nodes (if etcd node count >= 1; By default etcd node count is 0) + +For more information about the Advanced Settings see :ref:`flexible-kubernetes-clusters`. + +|cks-create-cluster-additional-settings.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) +- **description** (description for the Kubernetes cluster) - **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) +- **clustertype** (Define the type of cluster: `CloudManaged` (managed by CloudStack), `ExternalManaged` (managed by an external kubernetes provider). Defaults to `CloudManaged`) +- **kubernetesversionid** (Kubernetes version with which cluster to be launched; Required for CloudManaged clusters) +- **serviceofferingid** (the ID of the service offering for the Instances in the cluster; Required for CloudManaged clusters) +- **account** (an optional Account for the Instance. Must be used with domainId) +- **domainid** (an optional domainId for the Instance. 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) -- **controlnodes** (number of Kubernetes cluster control 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) +- **keypair** (name of the ssh key pair used to login to the Instances) +- **controlnodes** (number of Kubernetes cluster control 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 for manage clusters) - **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) +- **hypervisor** (an optional parameter to specify the hypervisor on which the Kubernetes cluster will be deployed) +- **nodeofferings** (an optional map parameter to set the service offerings for worker, control or etcd nodes. If this parameter is not set, then every VM in the cluster will be deployed using the default service offering set on the serviceofferingid parameter) +- **etcdnodes** (An optional integer parameter that specifies the number of etcd nodes in the cluster. The default value is 0. If set to a value greater than 0, dedicated etcd nodes are created separately from the master nodes.) +- **nodetemplates**: (an optional map parameter to set the template to be used by worker, control or etcd nodes. If not set, then every VM in the cluster will be deployed using the System VM template) +- **asnumber** (an optional parameter to set the AS Number of the Kubernetes cluster network) +- **cniconfigurationid** (an optional parameter to set the UUID of a registered CNI configuration) +- **cniconfigdetails** (an optional parameter to specify the parameters values for the variables defined in the CNI configuration) For example: @@ -197,7 +279,7 @@ For example: "endpoint": "https://172.20.20.12:6443/", "id": "74e3cc02-bbf7-438f-bfb0-9c193e90c1fb", "kubernetesversionid": "6668e999-fe6c-4a91-88d8-d10bcf280d02", - "kubernetesversionname": "v1.13.2", + "kubernetesversionname": "v1.33.1", "controlnodes": 1, "memory": "4096", "name": "Test", @@ -217,12 +299,12 @@ For example: } On successful creation, the new cluster will automatically be 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 was unable to provision the node virtual machines for the cluster or if the cluster API server is not accessible. +- Alert – When node Instances were successfully provisioned, and cluster API server is accessible but further provisioning steps could not be completed. +- Error – When the service was unable to provision the node Instances for the cluster or if the cluster API server is not accessible. .. note:: - A minimum of 2 cores of CPU and 2GB of RAM is needed for deployment. Therefore, the serviceofferingid parameter of createKubernetesCluster API must be provided with the ID of such compute offerings that conform to these requirements. - - Private docker registry related parameters of createKubenetesCluster 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 to true by admin beforehand. + - Private docker registry related parameters of createKubernetesCluster 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 to true by admin beforehand. Listing Kubernetes clusters ############################ @@ -236,6 +318,9 @@ Stopping Kubernetes cluster A running Kubernetes cluster can be stopped using either the stopKubernetesCluster API which takes id of the cluster as an input parameter or |cks-stop-action.png| action icon from UI. action icon is shown for a running cluster in the UI. +.. note:: + This operation is supported only for CloudManaged kubernetes cluster. + Starting a stopped Kubernetes cluster ###################################### @@ -243,6 +328,9 @@ A stopped Kubernetes cluster can be started using either the startKubernetesClus When the service fails to start a stopped cluster, the cluster will show in Alert state else it will show up as Running. +.. note:: + This operation is supported only for CloudManaged kubernetes cluster. + Scaling Kubernetes cluster ########################### @@ -253,12 +341,14 @@ A running or stopped Kubernetes cluster can be scaled using both API and UI. |ck scaleKubernetesCluster API can be used to scale a running (or stopped cluster) to a desired cluster size and service offering. It takes the 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) +- **serviceofferingid** (the ID of the new service offering for the Instances in the cluster) - **size** (number of Kubernetes cluster worker nodes) -Only running Kubernetes clusters can be scaled in 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. +Only running Kubernetes clusters can be scaled in size. When the service fails to scale the cluster, the cluster will show in Alert state else if the scaling is successful cluster will show up in Running state. -Note: Only up scaling is supported while scaling clusters for service offering. +.. note:: + - Only up scaling is supported while scaling clusters for service offering. + - This operation is supported only for CloudManaged kubernetes cluster Upgrading Kubernetes cluster ############################# @@ -274,14 +364,16 @@ upgradeKubernetesCluster API can be used to upgrade a running cluster. It takes When the service fails to upgrade the cluster, the cluster will show up in Alert state, else if successful, the cluster appears 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. +.. 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. + - This operation is supported only for CloudManaged kubernetes cluster Deleting Kubernetes cluster ############################ A kubernetes cluster can be deleted using either the deleteKubernetesCluster API which takes cluster id as the input parameter or the |cks-delete-action.png| action icon from the UI. -The Kubernetes service runs a background state scanner process which regularly checks the cluster health. For clusters in Alert state, this background process verifies their state and moves them to Running state if all node virtual machines of the cluster are running and the API server for the cluster is accessible. +The Kubernetes service runs a background state scanner process which regularly checks the cluster health. For clusters in Alert state, this background process verifies their state and moves them to Running state if all node Instances of the cluster are running and the API server for the cluster is accessible. Working with Kubernetes cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -299,12 +391,59 @@ The service provides functionality to access kubeconfig file for a running Kuber getKubernetesClusterConfig API can be used to retrieve kubeconfig file data for a cluster. It takes id of the cluster as the input parameter. +Note: The User Data and Metadata of the underlying host can be accessed by the container running on the CKS cluster. If you want prevent the access follow the below steps + +.. parsed-literal:: + + - The User Data and Metadata of the underlying worker-nodes can be accessed by the containers running on the CKS cluster + + For example: Deploy a container on a CKS cluster + + kubectl exec -it -- /bin/sh + + curl http://data-server/latest/meta-data/ + service-offering + availability-zone + local-ipv4 + local-hostname + public-ipv4 + public-hostname + instance-id + vm-id + public-keys + cloud-identifier + hypervisor-host-name + + curl http://data-server/latest/user-data/ + + + - If you want to prevent the access of User Data and Metadata from the containers running on CKS cluster, Execute the following yaml + + kubectl apply -f deny-meta-data.yaml + + apiVersion: networking.k8s.io/v1 + kind: NetworkPolicy + metadata: + name: deny-metadata-access + spec: + podSelector: {} + policyTypes: + - Egress + egress: + - to: + - ipBlock: + cidr: 169.254.188.68/32 + ports: + - protocol: TCP + port: 80 + + 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. +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| @@ -329,6 +468,372 @@ Token for dashboard login can be retrieved using the following command: # 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 +Kubernetes compatibility Matrix +################################# + ++--------------+---------------------------------+-----------------------------+-------------+ +|ACS Version | Supported Kubernetes Versions | CKS Template | SSH User | ++==============+=================================+=============================+=============+ +| 4.14.x | v1.11 onward (< 1.18) | CoreOS | core | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.15.x | v1.11 onward (< 1.18) | CoreOS | core | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.16.0 | v1.20 onward | SystemVM Template (Debian) | core | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.16.1 | v1.20 onward | SystemVM Template (Debian) | cloud | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.19.1 | v1.30 onward | SystemVM Template (Debian) | cloud | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.20.1 | v1.30 onward | SystemVM Template (Debian) | cloud | ++--------------+---------------------------------+-----------------------------+-------------+ +| 4.21.0 | v1.33 onward | SystemVM Template (Debian) | cloud | ++--------------+---------------------------------+-----------------------------+-------------+ + + +Adding/Removing Instances for an ExternalManaged Kubernetes Cluster +################################################################### +The Instances launched by the external kubernetes provider can be linked to the ExternalManaged kubernetes cluster. + +To add an Instance to an ExternalManaged Kubernetes cluster: + +.. code-block:: bash + + cmk add VirtualMachinesToKubernetesCluster id=59028a81-d9c9-46f6-bd16-8da918571c23 virtualmachineids=1d991764-3be8-4d2e-a9f1-2de2fc80ca72,97172931-286b-46c5-9427-ffc19315479e + +To remove an Instance from an ExternalManaged Kubernetes cluster: + +.. code-block:: bash + + cmk remove VirtualMachinesFromKubernetesCluster id=59028a81-d9c9-46f6-bd16-8da918571c23 virtualmachineids=1d991764-3be8-4d2e-a9f1-2de2fc80ca72,97172931-286b-46c5-9427-ffc19315479e + +.. note:: + These operations are only supported for an ExternalManaged Kubernetes Cluster + + +.. _flexible-kubernetes-clusters: + +Flexible Kubernetes Clusters +---------------------------- + +From 4.21.0, many enhancements have been added to CloudStack Kubernetes Service that allows users to: + +- Select the Hypervisor type for the Kubernetes Cluster nodes +- Specify different templates and/or service offerings for different types of Kubernetes Clusters nodes +- Use CKS-ready custom templates for Kubernetes cluster nodes marked as 'For CKS' +- Separate etcd nodes from control nodes of the Kubernetes clusters +- Add and remove a pre-created instance as a worker node to an existing Kubernetes cluster +- Mark Kubernetes cluster nodes for manual-only upgrade +- Dedicate specific hosts/clusters to a specific domain for CKS cluster deployment +- Use diverse CNI plugins (Calico, Cilium, etc) + +Build a custom template to use for Kubernetes clusters nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack provides a custom CKS-ready template based on Ubuntu 22.04 to be used for Kubernetes clusters nodes: https://download.cloudstack.org/testing/custom_templates/ubuntu/22.04/. + +This template contains all the required packages to be used as a Kubernetes cluster node. The default login credentials are: cloud:cloud. + +A user may decide not to use the provided CKS-ready template and build their own template. The following needs to be made sure is present on the template: + +- The following packages or the equivalent ones for the specific OS need to be installed: + + .. code-block:: bash + + cloud-init cloud-guest-utils conntrack apt-transport-https ca-certificates curl gnupg gnupg-agent software-properties-common gnupg lsb-release python3-json-pointer python3-jsonschema containerd.io + +- A user named `cloud` needs to be created and added to the sudoers list: + + .. code-block:: bash + + sudo useradd -m -s /bin/bash cloud + echo "cloud:" | sudo chpasswd + + # Edit /etc/sudoers file with: + cloud ALL=(ALL) NOPASSWD:ALL + +- Create the necessary directory /opt/bin: + + .. code-block:: bash + + sudo mkdir -p /opt/bin + +- Once the VM is deployed, place the Management Server’s SSH Public key at the cloud user’s authorized_keys file at ~/.ssh/authorized_keys + + +Registering a custom template for Kubernetes cluster nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the Kubernetes clusters nodes are deployed from the System VM template. On the Advanced Settings for Kubernetes clusters creation, CloudStack allows selecting templates for different types of nodes. + +To register a template that will be listed as an option for Kubernetes cluster nodes: + +- Set URL to the provided CKS-ready template at: https://download.cloudstack.org/testing/custom_templates/ubuntu/22.04/ or a custom template built from the section above. + +- Set the template specific values as usual for template registration. + +- Mark the option 'For CKS'. This ensures the template is considered as an option for Kubernetes cluster nodes on the Advanced Settings section for clusters creation. + +|cks-custom-template-registration.png| + +Separate etcd nodes from control nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, a CKS cluster has 0 dedicated etcd nodes, and the etcd service runs on the control nodes. If etcd node count is set to a value greater than or equal to 1 during cluster creation, CloudStack will provision separate nodes exclusively for the etcd service, isolating them from the control nodes with the desired template and service offering if specified. + +To use separate etcd nodes, it is required to build and register a CKS ISO version containing the etcd binaries as explained in: :ref:`kubernetes-supported-versions` + +For convenience, some CKS ISOs are uploaded to: https://download.cloudstack.org/testing/cks/custom_templates/iso-etcd/ + +Add an external VM Instance as a worker node to a Kubernetes cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Requirements for a VM Instance to be added as worker node to a Kubernetes cluster: + +- At least 8GB ROOT disk size, 2 CPU cores and 2GB RAM + +- The VM Instance must have a NIC on the Kubernetes cluster network + +- **The Management Server’s SSH Public key must be added at the cloud user’s authorized_keys file at `~/.ssh/authorized_keys`**. + +The VM Instances meeting the requirements above can be added to the Kubernetes cluster by the `addNodesToKubernetesCluster` API specifying: + +- **id** (UUID of the Kubernetes cluster. Required) +- **nodeids** (comma separated list of (external) node (physical or virtual machines) IDs that need to be added as worker nodes to an existing managed Kubernetes cluster (CKS). Required) +- **mountcksisoonvr** (optional parameter for Vmware only, uses the CKS cluster network VR to mount the CKS ISO) +- **manualupgrade** (optional parameter that indicates if the node is marked for manual upgrade and excluded from the Kubernetes cluster upgrade operation) + +.. note:: + Users will have the ability to add nodes to the Kubernetes cluster and mark them for manual upgrade. Once the nodes are marked for manual upgrade, the future cluster upgrade operations will exclude these nodes i.e., the Kubernetes version won't be upgraded. + +The following course of actions are taken: + +- Validation: The external node(s) are validated to ensure that all the above-mentioned prerequisites are present + +- Addition of port-forwarding rules and firewall rules (for isolated networks) + +- VM is rebooted with the Kubernetes configuration passed as user data + +- The ISO is attached either to the node or to the VR based on the value of `mountcksisoonvr` that is passed as a parameter to the addNodesToKubernetesCluster API (Vmware only). + +- The cluster enters Importing state until all the nodes are successfully added, and the number of Ready nodes is equal to the expected number of nodes to be added. + +- The process timeout is set by the setting: `cloud.kubernetes.cluster.add.node.timeout`. + +Removing an external worker node from a Kubernetes cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +External worker nodes can be removed from a Kubernetes cluster by the `removeNodesFromKubernetesCluster` API specifying: + +- **id** (UUID of the Kubernetes cluster. Required) +- **nodeids** (comma separated list of (external) node (physical or virtual machines) IDs that need to be removed from an existing managed Kubernetes cluster (CKS). Required) + +When node(s) are being removed from a Kubernetes cluster, the following happens: + +- On the control node, drain the specific node before it can be removed + +- Reset the corresponding worker node + +- Delete the worker node from the cluster on the control node + +- Remove the port-forwarding and firewall rules (for isolated networks) for the nodes being removed + +- The cluster enters RemovingNodes state until all the nodes are successfully removed, and the number of Ready nodes is equal to the expected number of nodes + +- The process timeout is set by the setting: `cloud.kubernetes.cluster.remove.node.timeout`. + +Dedicate specific hosts/clusters to a specific domain for CKS cluster deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Administrators are able to dedicate hosts to a domain or account. CloudStack will take the host dedication into consideration when deploying Kubernetes clusters. + +- When there are no hosts dedicated to the domain/account the user belongs, then the nodes will be deployed on any host. + +- When there are hosts dedicated to the domain/account the user belongs, then the nodes will be deployed on the dedicated hosts. + + .. note:: + By design the hosts dedication does not consider the deployment of system VMs on the dedicated hosts (SSVM, CPVM and Virtual Routers). In case the Kubernetes cluster is created on an unimplemented network then the Virtual Router of the network will not be deployed on the dedicated hosts. + +Affinity groups for CKS cluster nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From 4.23.0 onwards, users can specify host affinity or anti-affinity groups for different types of Kubernetes cluster nodes (control, worker, etcd) during cluster creation. This provides control over VM placement on hosts for high availability requirements. + +|cks-create-cluster-affinity-groups.png| + +To use affinity groups with CKS clusters: + +1. Create the desired affinity groups (host affinity or host anti-affinity) beforehand using the CloudStack UI or API. + +2. When creating a Kubernetes cluster, specify the affinity group mapping using the **nodeaffinitygroups** parameter. This parameter accepts a mapping of node types to affinity group UUIDs with two fields per entry: + + - ``node``: The node type (permitted values: ``worker``, ``control``, ``etcd``) + - ``affinitygroup``: The UUID of the desired affinity group + +Example using the API: + +.. code-block:: bash + + cmk create kubernetescluster name=MyCluster zoneid= kubernetesversionid= serviceofferingid= size=3 nodeaffinitygroups[0].node=worker nodeaffinitygroups[0].affinitygroup= + +Multiple affinity groups can be assigned to a single node type by providing comma-separated UUIDs: + +.. code-block:: bash + + nodeaffinitygroups[0].affinitygroup=, + +Different node types can have different affinity group configurations: + +.. code-block:: bash + + nodeaffinitygroups[0].node=control nodeaffinitygroups[0].affinitygroup= nodeaffinitygroups[1].node=worker nodeaffinitygroups[1].affinitygroup= + +The affinity group configuration is persisted and automatically applied when scaling the cluster - new worker nodes inherit the affinity group settings without requiring additional parameters. + +.. note:: + - When adding external worker nodes to an existing cluster using ``addNodesToKubernetesCluster``, the nodes are validated against any worker affinity groups configured for the cluster. + +Use diverse CNI plugins (Calico, Cilium, etc) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A CNI framework has also been added which provides end users the flexibility to use the CNI plugin of their choice. The CNI framework internally leverages the managed User data feature provided by CloudStack. + +Sample Calico CNI configuration data used which is appended to the existing Kubernetes control node user data is: + .. note:: + This Calico sample requires prior external BGP peering — without BGP the CKS deployment will not work as expected + +.. code-block:: bash + + #cloud-config + - for i in {1..3}; do curl https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/calico.yaml -o /home/cloud/calico.yaml && break || sleep 5; done + - until [ -f /home/cloud/success ]; do sleep 5; done + - echo "Kubectl apply file" + - for i in {1..3}; do sudo /opt/bin/kubectl create -f /home/cloud/calico.yaml && break || sleep 5; done + - export PATH=$PATH:/home/cloud + - | + cat << 'EOF' > /home/cloud/create-configs.sh + #!/bin/bash + cat << 'EOL' > /home/cloud/bgp-config.yaml + apiVersion: crd.projectcalico.org/v1 + kind: BGPConfiguration + metadata: + name: default + spec: + logSeverityScreen: Debug + asNumber: {{ AS_NUMBER }} + EOL + cat << 'EOL' > /home/cloud/bgp-peer.yaml + apiVersion: crd.projectcalico.org/v1 + kind: BGPPeer + metadata: + name: bgp-peer-1 + spec: + peerIP: {{ ds.meta_data.peer_ip_address }} + asNumber: {{ ds.meta_data.peer_as_number }} + EOL + EOF + - chmod +x /home/cloud/create-configs.sh + - /home/cloud/create-configs.sh + - for i in {1..3}; do sudo /opt/bin/kubectl apply -f /home/cloud/bgp-config.yaml && break || sleep 5; done + - for i in {1..3}; do sudo /opt/bin/kubectl apply -f /home/cloud/bgp-peer.yaml && break || sleep 5; done + + +The CNI Configuration creation allows specifying the parameters to be set as a comma separated list: + +|cks-cni-configuration-registration-sample.png| + +After a CNI Configuration is created, it can be appended to Kubernetes cluster nodes as part of 'Advanced Settings': + +|cks-cni-configuration-cluster-creation.png| + +For verification of the applied CNI Configuration, the following commands can be used: + +.. code-block:: bash + + root@cksclusteradditon-control-190ca0ce253:~# kubectl get pods -A + + NAMESPACE NAME READY STATUS RESTARTS AGE + + kube-system calico-kube-controllers-8d76c5f9b-pkhcv 1/1 Running 6 (44m ago) 2d21h + + kube-system calico-node-n4msg 1/1 Running 0 2d21h + + kube-system calico-node-pdz2w 1/1 Running 0 2d18h + + kube-system calico-node-slmg2 1/1 Running 0 2d21h + + + + root@cksclusteradditon-control-190ca0ce253:~# kubectl get bgppeer + + NAME AGE + + bgp-peer-1 2d22h + + + + root@cksclusteradditon-control-190ca0ce253:~# kubectl get bgpconfiguration + + NAME AGE + + default 2d22h + + + root@cksclusteradditon-control-190ca0ce253:~# kubectl describe bgpconfiguration + + Name: default + + Namespace: + + Labels: + + Annotations: + + API Version: crd.projectcalico.org/v1 + + Kind: BGPConfiguration + + Metadata: + + Creation Timestamp: 2024-07-19T08:25:14Z + + Generation: 1 + + Resource Version: 580 + + UID: 2b927b4e-82d3-4200-a3c1-9bf0cd5f5824 + + Spec: + + As Number: 65145 + + Log Severity Screen: Debug + + Events: + +There could be Calico routing edge case encountered in some environments. By default, Calico uses the 192.168.0.0/16 network for its pod IP pool when you install it with the standard manifests. To avoid potential routing conflicts with existing networks in your infrastructure, it's advisable to customize the Calico IP pool to use a different subnet that doesn't overlap with your current network setup. + +kubectl get ippool.crd.projectcalico.org -o yaml + +.. code-block:: bash + apiVersion: crd.projectcalico.org/v1 + kind: IPPool + metadata: + name: default-ipv4-ippool + spec: + cidr: 192.168.0.0/16 + ipipMode: Always + natOutgoing: true + disabled: false + +You can edit the IP pool to change the CIDR to a different subnet that fits your network architecture better. For example, you might choose to use 10.0.0.0/16. + +kubectl edit ippool default-ipv4-ippool + +and redeploy the pods + +kubectl delete pod --all -A + + .. |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 @@ -341,6 +846,10 @@ Token for dashboard login can be retrieved using the following command: :alt: Kubernetes clusters list. .. |cks-create-cluster-form.png| image:: /_static/images/cks-create-cluster-form.png :alt: Create Kubernetes Cluster form. +.. |cks-create-cluster-additional-settings.png| image:: /_static/images/cks-create-cluster-additional-settings.png + :alt: Create Kubernetes Cluster form with Advanced Settings. +.. |cks-create-cluster-affinity-groups.png| image:: /_static/images/cks-create-cluster-affinity-groups.png + :alt: Affinity groups selection in Create Kubernetes Cluster Advanced Settings. .. |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 @@ -359,3 +868,9 @@ Token for dashboard login can be retrieved using the following command: :alt: Upgrade Kubernetes Cluster form. .. |cks-versions.png| image:: /_static/images/cks-versions.png :alt: Supported Kubernetes versions list. +.. |cks-custom-template-registration.png| image:: /_static/images/cks-custom-template-registration.png + :alt: Custom Template Registration for Kubernetes cluster nodes. +.. |cks-cni-configuration-cluster-creation.png| image:: /_static/images/cks-cni-configuration-cluster-creation.png + :alt: Kubernetes cluster creation setting a CNI configuration. +.. |cks-cni-configuration-registration-sample.png| image:: /_static/images/cks-cni-configuration-registration-sample.png + :alt: CNI Configuration registration sample. diff --git a/source/plugins/index.rst b/source/plugins/index.rst index 661ec82c3c..fd0df5ed60 100644 --- a/source/plugins/index.rst +++ b/source/plugins/index.rst @@ -32,10 +32,13 @@ This is the Apache CloudStack Plugins guide. This section gives information for cloudian-connector nicira-plugin + nsx-plugin + netris-plugin vxlan ovs-plugin ipv6 quota cloudstack-kubernetes-service cloudstack-kubernetes-provider.rst + cloudstack-csi-driver.rst diff --git a/source/plugins/ipv6.rst b/source/plugins/ipv6.rst index 2a53cd5369..79078f3624 100644 --- a/source/plugins/ipv6.rst +++ b/source/plugins/ipv6.rst @@ -16,17 +16,13 @@ IPv6 Support in CloudStack =========================== +CloudStack has limited IPv6 support. It supports IPv6 for shared and isolated networks. It also supports IPv6 for VPC Network Tiers. -CloudStack supports Internet Protocol version 6 (IPv6), the recent -version of the Internet Protocol (IP) that defines routing the network -traffic. IPv6 uses a 128-bit address that exponentially expands the -current address space that is available to the users. IPv6 addresses -consist of eight groups of four hexadecimal digits separated by colons, -for example, 5001:0dt8:83a3:1012:1000:8s2e:0870:7454. CloudStack -supports IPv6 for public IPs in shared networks. With IPv6 support, VMs -in shared networks can obtain both IPv4 and IPv6 addresses from the DHCP -server. You can deploy VMs either in a IPv6 or IPv4 network, or in a -dual network environment. If IPv6 network is used, the VM generates a +Shared network +-------------- +With IPv6 support, Instances in shared networks can obtain both IPv4 and IPv6 addresses from the DHCP +server. You can deploy Instances either in a IPv6 or IPv4 network, or in a +dual network environment. If IPv6 network is used, the Instance generates a link-local IPv6 address by itself, and receives a stateful IPv6 address from the DHCPv6 server. @@ -37,22 +33,22 @@ Here's the sequence of events when IPv6 is used: #. The administrator creates an IPv6 shared network in an advanced zone. -#. The user deploys a VM in an IPv6 shared network. +#. The user deploys an Instance in an IPv6 shared network. -#. The user VM generates an IPv6 link local address by itself, and gets +#. The user Instance generates an IPv6 link local address by itself, and gets an IPv6 global or site local address through DHCPv6. Prerequisites and Guidelines ----------------------------- +############################ Consider the following: - CIDR size must be 64 for IPv6 networks. -- The DHCP client of the guest VMs should support generating DUID based +- The DHCP client of the Guest Instances should support generating DUID based on Link-layer Address (DUID- LL). DUID-LL derives from the MAC - address of guest VMs, and therefore the user VM can be identified by + address of Guest Instances, and therefore the user Instance can be identified by using DUID. See `Dynamic Host Configuration Protocol for IPv6 `__\ for more information. @@ -69,56 +65,56 @@ Consider the following: available for address configuration in addition to any IPs set by using stateless address auto-configuration. -- Use the System VM template exclusively designed to support IPv6. - Download the System VM template from +- Use the System VM Template exclusively designed to support IPv6. + Download the System VM Template from `http://download.cloudstack.org/systemvm/ `__. - The concept of Default Network applies to IPv6 networks. However, unlike IPv4 CloudStack does not control the routing information of IPv6 in shared network; the choice of Default Network will not affect - the routing in the user VM. + the routing in the user Instance. - A shared network cannot be IPv6 only. Therefore, it is necessary to configure the IPv4 address range for the shared network with IPv6 addresses. The IPv4 range can be of a public or internal IPv4 network. - In a multiple shared network, the default route is set by the rack router, rather than the DHCP server, which is out of CloudStack - control. Therefore, in order for the user VM to get only the default - route from the default NIC, modify the configuration of the user VM, + control. Therefore, in order for the user Instance to get only the default + route from the default NIC, modify the configuration of the user Instance, and set non-default NIC's ``accept_ra`` to 0 explicitly. The ``accept_ra`` parameter accepts Router Advertisements and auto-configure ``/proc/sys/net/ipv6/conf/interface`` with received data. -Limitations of IPv6 in CloudStack ---------------------------------- +Limitations +########### The following are not yet supported: #. Security groups -#. Userdata and metadata +#. User Data and metadata #. Passwords -Guest VM Configuration for DHCPv6 ---------------------------------- +Guest Instance Configuration for DHCPv6 +####################################### -For the guest VMs to get IPv6 address, run dhclient command manually on -each of the VMs. Use DUID-LL to set up dhclient. +For the Guest Instances to get IPv6 address, run dhclient command manually on +each of the Instances. Use DUID-LL to set up dhclient. .. note:: - The IPv6 address is lost when a VM is stopped and started. Therefore, - use the same procedure to get an IPv6 address when a VM is stopped and + The IPv6 address is lost when an Instance is stopped and started. Therefore, + use the same procedure to get an IPv6 address when an Instance is stopped and started. #. Set up dhclient by using DUID-LL. Perform the following for DHCP Client 4.2 and above: - #. Run the following command on the selected VM to get the dhcpv6 + #. Run the following command on the selected Instance to get the dhcpv6 offer from VR: .. parsed-literal:: @@ -199,3 +195,145 @@ each of the VMs. Use DUID-LL to set up dhclient. iface eth0 inet6 dhcp autoconf 0 accept_ra 1 + + +Isolated network and VPC Network Tier +------------------------------------- + +.. note:: + - The IPv6 support for isolated networks and VPC Network Tiers is available from version 4.17.0. + + - The IPv6 isolated networks and VPC Network Tiers only supports **Static routing**, i.e, the administrator will need to add upstream routes for routing to work inside the networks. + + - IPv6 only isolated networks and VPC Network Tiers are not supported currently. Public network for IPv6 supported isolated networks and VPC Network Tiers must be on the same VLAN for both IPv4 and IPv6. + +Guest Instances in an isolated network or VPC Network Tier can obtain both IPv4 and IPv6 IP addresses by using a supported network offering and appropriate configurations for IPv6 support by the administrator. +Both VR for such networks and the Guest Instances using these networks obtain a SLAAC based IPv6 address. While VR is assigned an IPv6 address from the public IPv6 range, Guest Instances get their IPv6 addresses from the IPv6 subnet assigned to the network. + +Here's the sequence of events when IPv6 is used: + +#. The administrator sets global configuration - ``ipv6.offering.enabled`` to **true**. + +#. The administrator adds a public IPv6 range in an advanced zone. + +#. The administrator adds an IPv6 prefix for guest traffic type for the zone. + +#. The administrator creates a network or VPC offering with IPv4 + IPv6 (Dual stack) support. + +#. The user deploys an isolated network with the IPv6 supported network offering. For VPC, user creates a VPC with IPv6 supported VPC offering and then deploys a Network Tier with IPv6 supported network offering. + +#. CloudStack assigns a SLAAC based public IPv6 address to the network from the public IPv6 range of the zone. It also assigns an IPv6 subnet to the network from the guest IPv6 prefix for the zone. See `SLAAC `__\ for more information. + +#. The user deploys a Guest Instance in the network. The Instance is assigned a SLAAC based IPv6 address from the guest IPv6 subnet of the network. + + +Prerequisites and Guidelines +############################ + +Consider the following: + +- CIDR size for the public IPv6 range for a zone must be 64. + +- CIDR size for the guest IPv6 prefix for the zone must be lesser than 64. Each guest network is assigned a subnet from this prefix with CIDR size 64 therefore only as many IPv6 supporting guest networks can be deployed from the guest prefix as the number of subnets with CIDR size 64. + +- Currently, a guest network cannot be IPv6 only and it can only be either IPv4 only or Dual Stack (both IPv4 + IPv6). + +- Once a public IPv6 address and guest subnet are assigned to the network or the network is successfully, the operator must update routing in the upstream router. For this, CloudStack returns the gateway and subnet for the network with listNetworks API response. + + +Adding a Public IPv6 Range +########################## + +The administrator can use both UI and API to add a public IPv6 range. UI is the preferable option. +Option to add a new public IPv6 range in the UI can be found in Infrastructure > Zones > Zone details > Physical Network tab > Physical network details > Traffic Types tab > Public > *Add IP range*. +In the Add IP range form, IPv6 can be selected as the IP Range Type. IPv6 Gateway and CIDR must be provided and optionally a VLAN/VNI can be provided. + +Alternatively, ``createVlanIpRange`` API can be used to add a new public IPv6 range. + +|add-public-ipv6-range-form.png| + + + + .. note:: + - The public IPv6 address range or CIDR must be added with same VLAN as that of public IPv4 address range. + + - As SLAAC based public IPv6 addresses will be assigned to the networks therefore public IPv6 range must be added without specifying start and end IP addresses. + + +Adding Guest IPv6 Prefix +######################## + +Again, both UI and API to add a guest IPv6 prefix. UI is the preferable option. +Option to add a new public Ipv6 range in the UI can be found in Infrastructure > Zones > Zone details > Physical Network tab > Physical network details > Traffic Types tab > Guest > *Add IPv6 prefix*. +In the Add IPv6 prefix form, an IPv6 prefix with CIDR size lesser than 64 must be provided. + +Alternatively, ``createGuestNetworkIpv6Prefix`` API can be used to add a new guest IPv6 prefix. + +|add-guest-ipv6-prefix-form.png| + + +Adding Network or VPC Offering with IPv6 Support +################################################ + +To create an IPv6 supported network or VPC offering, global configuration - ``ipv6.offering.enabled`` must be set to **true**. + +With 4.17.0, a new parameter - ``internetprotocol`` has been added to: + - the ``createNetworkOffering`` API which can be used to create a network offering with IPv6 support by using the value dualstack. + - the ``createVPCOffering`` API which can be used to create a VPC offering with IPv6 support by using the value dualstack. +Corresponding option has also been provided in the UI form creating network/VPC offering: + +|add-ipv6-network-offering-form.png| + +|add-ipv6-vpc-offering-form.png| + + +Adding Upstream Route +##################### + +Currently, CloudStack supports IPv6 isolated networks and VPC Network Tiers only with **static** routes and therefore the administrator needs to add upstream IPv6 routes once a network is successfully deployed. +To facilitate the automation, *CloudStack Event Notification* can be used. CloudStack will generate appropriate events on network creation or deletion and while assigning or releasing a public IPv6 address for a network. Based on the events the corresponding network can be queried for the IPv6 routes that it needs configured in upstream network. +Upstream IPv6 routes required by an IPv6 supported isolated network or VPC Network Tier are also shown in the UI in the network details. + +|network-details-upstream-ipv6-routes.png| + + +IPv6 Firewall +############# + +For using and managing firewall rules with an IPv6 supported isolated network, CloudStack provides following APIs: + +- ``listIpv6FirewallRules`` - To list existing IPv6 firewall rules for a network. +- ``createIpv6FirewallRule`` - To create a new IPv6 firewall rules for a network. +- ``updateIpv6FirewallRule`` - To update an existing IPv6 firewall rules for a network. +- ``deleteIpv6FirewallRule`` - To delete an existing IPv6 firewall rules for a network. + +These operations are also available using UI in the network details view of an IPv6 supported network. + +|network-details-ipv6-firewall.png| + + +IPv6 ACL +######## + +IPv6 ACL rules for an IPv6 supported VPC Network Tier can be managed using Network ACLs for the VPC. IPv6 CIDRs can be specified while adding or updating an ACL rule. + +|add-ipv6-acl-rule-form.png| +|ipv6-acl-list.png| + + +.. |add-public-ipv6-range-form.png| image:: /_static/images/add-public-ipv6-range-form.png + :alt: Add Public IPv6 Range form. +.. |add-guest-ipv6-prefix-form.png| image:: /_static/images/add-guest-ipv6-prefix-form.png + :alt: Add Guest IPv6 Prefix form. +.. |add-ipv6-network-offering-form.png| image:: /_static/images/add-ipv6-network-offering-form.png + :alt: Add IPv6 supported Network Offering form. +.. |add-ipv6-vpc-offering-form.png| image:: /_static/images/add-ipv6-vpc-offering-form.png + :alt: Add IPv6 supported VPC Offering form. +.. |network-details-upstream-ipv6-routes.png| image:: /_static/images/network-details-upstream-ipv6-routes.png + :alt: Upstream IPv6 routes in network details. +.. |network-details-ipv6-firewall.png| image:: /_static/images/network-details-ipv6-firewall.png + :alt: IPv6 Firewall management in network details. +.. |add-ipv6-acl-rule-form.png| image:: /_static/images/add-ipv6-acl-rule-form.png + :alt: Add IPv6 ACL rule. +.. |ipv6-acl-list.png| image:: /_static/images/ipv6-acl-list.png + :alt: IPv6 ACL rule in Network ACL. diff --git a/source/plugins/midonet.rst b/source/plugins/midonet.rst index fab489e092..a7de6d57ac 100644 --- a/source/plugins/midonet.rst +++ b/source/plugins/midonet.rst @@ -21,7 +21,7 @@ Introduction to the MidoNet Plugin ---------------------------------- The MidoNet plugin allows CloudStack to use the MidoNet virtualized -networking solution as a provider for CloudStack networks and services. For +networking solution as a provider for CloudStack Networks and services. For more information on MidoNet and how it works, see http://www.midokura.com/midonet/. @@ -34,9 +34,9 @@ Features of the MidoNet Plugin combination with MidoNet. In CloudStack release 4.2.0 this plugin supports several services in the -Advanced Isolated network mode. +Advanced Isolated Network mode. -When tenants create new isolated layer 3 networks, instead of spinning +When tenants create new isolated layer 3 Networks, instead of spinning up extra Virtual Router VMs, the relevant L3 elements (routers etc) are created in the MidoNet virtual topology by making the appropriate calls to the MidoNet API. Instead of using VLANs, isolation is provided by @@ -69,8 +69,8 @@ the MidoNet Agent, and the MidoNet API server must be available. Please consult the MidoNet User Guide for more information. The following section describes the CloudStack side setup. -#. CloudStack needs to have at least one physical network with the - isolation method set to "MIDO". This network should be enabled for +#. CloudStack needs to have at least one physical Network with the + isolation method set to "MIDO". This Network should be enabled for the Guest and Public traffic types. #. Next, we need to set the following CloudStack settings under "Global @@ -121,8 +121,8 @@ section describes the CloudStack side setup. Enabling the MidoNet service provider via the UI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To allow CloudStack to use the MidoNet Plugin the network service provider -needs to be enabled on the physical network. +To allow CloudStack to use the MidoNet Plugin the Network service provider +needs to be enabled on the physical Network. The steps to enable via the UI are as follows: @@ -152,11 +152,11 @@ To enable via the API, use the following API calls: - name = "MidoNet" -- physicalnetworkid = +- physicalnetworkid = *updateNetworkServiceProvider* -- id = +- id = - state = "Enabled" diff --git a/source/plugins/netris-plugin.rst b/source/plugins/netris-plugin.rst new file mode 100644 index 0000000000..dabf063b09 --- /dev/null +++ b/source/plugins/netris-plugin.rst @@ -0,0 +1,249 @@ +.. 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. + +The Netris Plugin +================= + +Introduction +------------ + +The Netris Plugin introduces Netris as a network service provider in CloudStack to be able to create and manage Virtual Private Clouds (VPCs) in CloudStack, being able to orchestrate the following network functionalities: + +- Network segmentation with Netris-VXLAN isolation method +- Routing between "public" IP and network segments with an ACS ROUTED mode offering +- SourceNAT, DNAT, 1:1 NAT between "public" IP and network segments with an ACS NATTED mode offering +- Routing between VPC network segments (tiers in ACS nomenclature) +- Access Lists (ACLs) between VPC tiers and "public" network (TCP, UDP, ICMP) both as global egress rules and "public" IP specific ingress rules. +- ACLs between VPC network tiers (TCP, UDP, ICMP) +- External load balancing – between VPC network tiers and "public" IP +- Internal load balancing – between VPC network tiers +- CloudStack Virtual Router services (DHCP, DNS, UserData, Password Injection, etc…) + + +Supported Versions +------------------ + ++--------------+----------------------+----------------+ +| Hypervisor | CloudStack Version | Netris Version | ++==============+======================+================+ +| KVM | >= 4.21 | 4.4.0 | ++--------------+----------------------+----------------+ + +Table: Supported Versions + +Configuration +------------- + +Prerequisites +~~~~~~~~~~~~~ + +The Netris plugin is enabled by the 'netris.plugin.enable' setting, which is false by default. It enables the Netris Plugin on CloudStack when it is set to true. The global setting is non-dynamic, that is, the management server would need to be restarted after being modified. + +Zone creation +~~~~~~~~~~~~~ + +The CloudStack Zone creation wizard is extended: + +.. image:: ../_static/images/netris-isolation-method.png + :width: 600px + :align: center + +- A new isolation method is added for the Core zone, with Advanced networking and KVM hypervisor: NETRIS + +- When the NETRIS isolation method is selected, new steps are added to the zone creation wizard: + - Netris Provider: in this step the administrator must provide: + - Netris provider URL along with an internal name for reference + - Netris provider credentials to login into the Netris provider + - Site name: The Netris Site Name to be linked to + - Admin Tenant Name: The name of the Admin Tenant on the Netris provider + - Netris tag: A tag to be used on each Netris VNET creation + + .. image:: ../_static/images/netris-provider-config.png + :width: 600px + :align: center + + - Public traffic and Netris IP Pool: The public traffic is split in two sections. + - Public traffic: The first Public IP range defined on this section will be marked for system VMs (and a tag will be displayed accordingly, with the name 'systemvm'). The next Public IP ranges defined on this section will be available for VR Public IPs. + + .. image:: ../_static/images/netris-sysvm-vr-ip-range.png + :width: 600px + :align: center + + - Netris IP Pool: Administrators must provide the Public IP range to be used by VPC operations: Source NAT, Load Balancing, Port Forwarding, Static NAT (this range is marked with the tag 'netris') + + .. image:: ../_static/images/netris-public-ip-pool.png + :width: 600px + :align: center + +- When a new zone is being created, CloudStack will check the Public IP ranges defined and will perform the following actions on Netris: + - Create an IPAM allocation for the Netris IP Pool range linked to the default VPC. + - If an existing IPAM allocation contains the Netris IP Pool provided, then the range must be created as a new IPAM subnet as a child entity of the existing allocation on Netris, with purpose: 'common'. The 'common' subnet purpose allows creating 'nat' and 'load-balancer' child subnets. + +.. note:: + **Important:** + Please note CloudStack expects the public IP ranges defined in the same order as the zone wizard creation displays them. The same order must be preserved in case of adding/editing/removing public IP ranges: + + - System VM Public Range + - VRs Public Range + - Netris Public Range + +The subsequent steps of zone creation remain unchanged and once the zone is successfully created and enabled, the system VMs come up with IPs from the Public IP Range reserved for System VMs (not the Netris public IP range). + +VPC creation on Netris +~~~~~~~~~~~~~~~~~~~~~~ + +VPC creation on CloudStack performs the following actions on Netris: + +- A new VPC is created for the Admin Tenant provided at the zone creation phase, with the name convention: D-A-Z-V-, where: + - domainID: Internal database ID of the domain + - accountID: Internal database ID of the account + - zoneID: Internal database ID of the VPC + - vpcName: Name of the VPC + +- A new IPAM allocation is created for the VPC Guest CIDR, with the following parameters: + - Prefix: The VPC CIDR + - Name: D-A-Z-V-, where: + - vpcCidr: is the CIDR defined for the VPC + - VPC: The new VPC created on the step above + +- Source NAT is created for VPC in NAT mode + +VPC Tier creation on Netris +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +VPC Tier creation on CloudStack performs the following actions on Netris: + +- A new IPAM subnet is created for the VPC Tier, with the following parameters: + - Prefix: The VPC Tier CIDR + - Name: D-A-Z-N-, where: + - networkID: The internal database ID of the network tier + - vpcTierCidr: is the CIDR defined for the VPC Tier + - Purpose: 'common' + - VPC: The VPC created on the step above + +- A new vNet is created, with the following parameters: + - Name: D-A-Z-N-, where: + - vpcTierName: is the VPC Tier name + - VPC: The VPC created on the step above + - VXLAN ID: A random VXLAN from the range provided on the zone creation + - VLAN ID: Disabled + - Tags: The tag set on the zone creation + - IP Gateway: The VPC Tier gateway IP, from the subnet created on the step above. +- ACLs are created on Netris + +- The VPC tiers created from the default VPC network offering for Netris – Routed Mode extends the IPAM Subnet creation for the VPC Tier Guest CIDR by setting the parameter: + - Global Routing = true. This parameter allows advertising the IPs for the VPC tier (required for Routed mode) + +.. note:: +Important: Please consider at least one running VM per VPC tier to prevent VPC tier state transition to Allocated state + + +Supported VPC Services +~~~~~~~~~~~~~~~~~~~~~~ + +· The following operations are supported for VPCs created from the default **VPC offering for Netris – NAT mode**: + - Source NAT: + - A new IPAM subnet is created for the Source NAT IP of the VPC, under the Netris IP pool IPAM allocation, with the following parameters: + - **Prefix**: /32, where SOURCE_NAT_IP is the VPC Source NAT IP + - **Purpose**: 'nat' + - **VPC**: Default VPC + - **Name**: D-A-Z-V- + + - A new NAT rule is created with the following parameters: + - **Action**: SNAT + - **Protocol**: ALL + - **VPC**: The associated VPC + - **Name**: D-A-Z-V-SNAT + - **Source Address**: The VPC CIDR + - **Destination Address**: 0.0.0.0/0 + - **SNAT to IP**: true, set to the Source NAT Public IP + + - Port forwarding rules: + - A new IPAM subnet is created for the Public IP, under the Netris IP Pool IPAM allocation, with the following parameters: + - **Prefix**: /32, where PUBLIC_IP is the selected free public IP + - **Purpose**: 'nat' + - **VPC**: Default VPC + - **Name**: D-A-Z-V- + + - A new NAT rule is created with the following parameters: + - **Action**: DNAT + - **VPC**: The associated VPC + - **Name**: D-A-Z-V-DNAT-R, where: + - **Rule ID**: The internal database ID of the port forwarding rule + - **Protocol**: The protocol for the port forwarding rule + - **Source Address**: 0.0.0.0/0 + - **Source Port**: 1-65535 + - **Destination Address**: The port forwarding Public IP + - **Destination Port**: The port forwarding rule public port + - **DNAT to IP**: /32, where VM_IP: is the VM guest IP + - **DNAT to port**: The port forwarding rule private port + + - Static NAT: + - A new IPAM subnet is created for the Public IP, under the Netris IP Pool IPAM allocation, with the following parameters: + - **Prefix**: /32, where PUBLIC_IP is the selected free public IP + - **Purpose**: 'nat' + - **VPC**: Default VPC + - **Name**: D-A-Z-V- + + - A new NAT rule is created with the following parameters: + - **Action**: DNAT + - **VPC**: The associated VPC + - **Name**: D-A-Z-V-STATICNAT: + - **Protocol**: ALL + - **Source Address**: 0.0.0.0/0 + - **Destination Address**: The port forwarding Public IP + - **DNAT to IP**: /32, where VM_IP: is the VM guest IP + + + - Load Balancing: + - A new IPAM subnet is created for the Public IP, under the Netris IP Pool IPAM allocation, with the following parameters: + - **Prefix**: /32, where PUBLIC_IP is the selected free public IP + - **Purpose**: 'load-balancer' + - **VPC**: Default VPC + - **Name**: D-A-Z-V- + + - A new L4 Load Balancer is created with the following parameters: + - **Action**: DNAT + - **VPC**: The associated VPC + - **Name**: D-A-Z-V-LB, where: + - **lbID**: The internal database ID of the load balancer + - **Protocol**: The protocol for the load balancer + - **Frontend Address**: The load balancer Public IP + - **Frontend Port**: The load balancer public port + - For each VM added to the load balancer: + - **Backend address**: The guest VM IP + - **Backend port**: The load balancer private port + + - ACLs + - A new ACL rule is created for each CloudStack ACL rule defined on the network tier ACL: + - **Name**: D-A-Z-V-N-ACL, where: + - **aclID**: The internal database ID of the ACL rule + - **VPC**: The associated VPC + - **Protocol**: The selected protocol for the ACL Rule + - **Action**: 'permit' or 'deny' matching the selected Allow or Deny action on CloudStack + - If the traffic type is **Ingress**: + - **Source Address**: The ACL rule CIDR + - **Source Port**: 1-65535 + - **Destination Address**: The VPC Tier CIDR + - **Destination Port**: X-Y, where: + - *X*: The ACL rule start port + - *Y*: The ACL rule end port + - If the traffic type is Egress: + - **Reverse**: true + - **Source Address**: The VPC Tier CIDR + - **Source Port**: 1-65535 + - **Destination Address**: The ACL rule CIDR + - **Destination Port**: X-Y, where: + - *X*: The ACL rule start port + - *Y*: The ACL rule end port \ No newline at end of file diff --git a/source/plugins/nicira-plugin.rst b/source/plugins/nicira-plugin.rst index 2fa447b4c3..6e1f780e8d 100644 --- a/source/plugins/nicira-plugin.rst +++ b/source/plugins/nicira-plugin.rst @@ -21,15 +21,15 @@ Introduction to the Nicira NVP Plugin ------------------------------------- The Nicira NVP plugin adds Nicira NVP as one of the available SDN -implementations in CloudStack. With the plugin an exisiting Nicira NVP -setup can be used by CloudStack to implement isolated guest networks and +implementations in CloudStack. With the plugin an existing Nicira NVP +setup can be used by CloudStack to implement isolated guest Networks and to provide additional services like routing and NAT. Features of the Nicira NVP Plugin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following table lists the CloudStack network services provided by +The following table lists the CloudStack Network services provided by the Nicira NVP Plugin. .. cssclass:: table-striped table-bordered table-hover @@ -103,8 +103,8 @@ Make sure you have the following information ready: Zone Configuration ~~~~~~~~~~~~~~~~~~ -CloudStack needs to have at least one physical network with the isolation -method set to "STT". This network should be enabled for the Guest +CloudStack needs to have at least one physical Network with the isolation +method set to "STT". This Network should be enabled for the Guest traffic type. .. note:: @@ -115,14 +115,14 @@ traffic type. .. figure:: /_static/images/nvp-physical-network-stt.png :align: center - :alt: a screenshot of a physical network with the STT isolation type + :alt: a screenshot of a physical Network with the STT isolation type Enabling the service provider ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Nicira NVP provider is disabled by default. Navigate to the "Network -Service Providers" configuration of the physical network with the STT +Service Providers" configuration of the physical Network with the STT isolation type. Navigate to the Nicira NVP provider and press the "Enable Provider" button. @@ -140,9 +140,9 @@ Device Management ~~~~~~~~~~~~~~~~~ In CloudStack a Nicira NVP setup is considered a "device" that can be added -and removed from a physical network. To complete the configuration of +and removed from a physical Network. To complete the configuration of the Nicira NVP plugin a device needs to be added to the physical -network. Press the "Add NVP Controller" button on the provider panel and +Network. Press the "Add NVP Controller" button on the provider panel and enter the configuration details. .. figure:: /_static/images/nvp-physical-network-stt.png @@ -153,7 +153,7 @@ enter the configuration details. Network Offerings ~~~~~~~~~~~~~~~~~ -Using the Nicira NVP plugin requires a network offering with Virtual +Using the Nicira NVP plugin requires a Network offering with Virtual Networking enabled and configured to use the NiciraNvp element. Typical use cases combine services from the Virtual Router appliance and the Nicira NVP plugin. @@ -184,17 +184,17 @@ Nicira NVP plugin. | Virtual Networking | NiciraNVP | +----------------------+-----------------+ -Table: Isolated network offering with regular services from the Virtual +Table: Isolated Network offering with regular services from the Virtual Router. .. figure:: /_static/images/nvp-physical-network-stt.png :align: center - :alt: a screenshot of a network offering. + :alt: a screenshot of a Network offering. .. note:: - The tag in the network offering should be set to the name of the - physical network with the NVP provider. + The tag in the Network offering should be set to the name of the + physical Network with the NVP provider. Isolated network with network services. The virtual router is still required to provide network services like dns and dhcp. @@ -242,14 +242,14 @@ Logical Switch VPC Offering with Nicira NVP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To allow a VPC to use the Nicira NVP plugin to provision networks, a new +To allow a VPC to use the Nicira NVP plugin to provision Networks, a new VPC offering needs to be created which allows the Virtual Networking service to be implemented by NiciraNVP. This is not currently possible with the UI. The API does provide the proper calls to create a VPC offering with Virtual Networking enabled. However due to a limitation in the 4.1 API it is not possible to select -the provider for this network service. To configure the VPC offering +the provider for this Network service. To configure the VPC offering with the NiciraNVP provider edit the database table 'vpc\_offering\_service\_map' and change the provider to NiciraNvp for the service 'Connectivity' @@ -272,8 +272,8 @@ provider 'NiciraNvp' VPC Network Offerings ~~~~~~~~~~~~~~~~~~~~~ -The VPC needs specific network offerings with the VPC flag enabled. -Otherwise these network offerings are identical to regular network +The VPC needs specific Network offerings with the VPC flag enabled. +Otherwise these Network offerings are identical to regular Network offerings. To allow VPC networks with a Nicira NVP isolated network the offerings need to support the Virtual Networking service with the NiciraNVP provider. diff --git a/source/plugins/nsx-plugin.rst b/source/plugins/nsx-plugin.rst new file mode 100644 index 0000000000..b88139f09b --- /dev/null +++ b/source/plugins/nsx-plugin.rst @@ -0,0 +1,229 @@ +.. 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. + + +The VMware NSX Plugin +===================== + +Introduction +------------ + +The VMware NSX Plugin introduces VMware NSX 4 as a network service provider in CloudStack to be able to create and manage Virtual Private Clouds (VPCs) in CloudStack, being able to orchestrate the following network functionalities: + +- Routing between VPC network tiers (NSX segments) +- Access Lists (ACLs) between VPC tiers and "public" network (TCP, UDP, ICMP) both as global egress rules and “public” IP specific ingress rules. +- ACLs between VPC network tiers (TCP, UDP, ICMP) +- Port Forwarding between “public” networks and VPC network tier +- External load balancing – between VPCs network tiers and “public” networks (runs on Edge Cluster) +- Internal load balancing – between VPC network tiers +- Password injection, User Data and SSH Keys +- External, Internal DNS +- DHCP +- Kubernetes host orchestration, supporting CKS on VPCs + +Supported Versions +------------------ + +.. cssclass:: table-striped table-bordered table-hover + ++--------------+----------------------+--------------------+ +| Hypervisor | CloudStack Version | VMware NSX Version | ++==============+======================+====================+ +| VMware | >= 4.20 | 4.1.0 | ++--------------+----------------------+--------------------+ + +Table: Supported Versions + +Configuration +------------- + +Prerequisites +~~~~~~~~~~~~~ + +The VMware NSX plugin is enabled by the 'nsx.plugin.enable' setting, false by default. It enables the NSX Plugin on CloudStack when it is set to true. The global setting is non-dynamic, that is, the management server would need to be restarted after being modified. + +Prior to creating the zone, ensure that the global setting: 'vmware.management.portgroup' is set to the correct management network for ESXi hosts. + +Zone creation +~~~~~~~~~~~~~ + +For an NSX-based zone, the administrator will have to create at least 2 physical networks, one for Public and Guest networks with **NSX** isolation method and one for Management (and / or storage networks), +which uses VLAN isolation method. + +**Physical network for Public and Guest traffic:** + Isolation method: NSX + VLAN ID must be empty + vSwitch type: distributed virtual switch (dvSwitch) + vSwitch name: name of the dvSwitch to handle NSX traffic + +**Physical network for Management traffic:** + Isolation method: VLAN + VLAN ID: ID for Management traffic + vSwitch type: distributed virtual switch (dvSwitch) + vSwitch name: name of the dvSwitch to handle Management traffic. + + +An example of physical networks setup: + +.. |nsx-phy-networks.png| image:: /_static/images/nsx-phy-networks.png + :alt: Physical Networks with NSX + +The next stage of zone creation would be to link the NSX controller to the CloudStack. + +.. |nsx-provider.png| image:: /_static/images/nsx-provider.png + :alt: NSX Provider details + +The administrator then needs to setup the IP ranges for Public and NSX Public traffic. + - Public Traffic: IP range for non-NSX public traffic used by system VMs + - NSX Public Traffic: IP range to use for Public IP Addresses on NSX-based VPCs or Isolated Networks. + +.. |nsx-public-traffic.png| image:: /_static/images/nsx-public-traffic.png + :alt: NSX Traffic + +The subsequent steps of zone creation remain unchanged and once the zone is successfully created and enabled, the system VMs come up with IPs from the Public IP Range (not the NSX public IP range). + +VPC creation on NSX +~~~~~~~~~~~~~~~~~~~~ + +When a VPC is created in CloudStack, the following operations occur on NSX end: + - CloudStack creates a Tier1 Gateway with the following: + + - ID and name on NSX: D-A-Z-V + - Linked Tier0 Gateway: the Tier0 Gateway provided on the NSX Controller creation in CloudStack + - For NAT mode VPCs, the following Route Advertisement settings are enabled: + - All IPSec Local Endpoints + - All NAT IPs + - All LB VIP Routes + - For ROUTED mode VPCs, the following Route Advertisement settings are enabled: + - All IPSec Local Endpoints + - All NAT IPs + - All LB VIP Routes + - All Connected Segments & Service Ports + + - The VPC Virtual Router acquires a free IP address on from the NSX Public Range and sets it as the Source NAT IP of the VPC. + - A new NAT Rule is created on NSX: + - ID and Name: D-A-Z-V-NAT + - Action: SNAT + - Source IP: Any + - Destination IP: Any + - Translated IP: The Source NAT IP of the VPC (selected from the NSX Public Range) + + +VPC Tier creation on NSX +~~~~~~~~~~~~~~~~~~~~~~~~~ + +On VPC network tier creation, CloudStack creates the following NSX elements: + - A Segment is linked to the VPC Tier1 Gateway with the following: + - ID and name on NSX: D-A-Z-V-S + - Linked Tier1 Gateway: The VPC Tier1 Gateway with name: D-A-Z-V + - Linked Transport Zone: The Transport Zone provided on NSX Controller creation in CloudStack + - Subnets: The VPC network tier CIDR provided on CloudStack + + - A Group under Inventory with the following: + - ID and name on NSX: D-A-Z-V-S (same as the segment) + - Group members: The created NSX segment + +VPC network ACL creation +~~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack allows creating ACL rules for NSX based network tiers. The supported protocols for creating NSX based ACL rules are:are TCP, UDP and ICMP. +Network ACLs can be assigned to any network tier in the VPC during network tier creation or an existing ACL on the network tier can be replaced. + +VPC tier Implementation +~~~~~~~~~~~~~~~~~~~~~~~~ + +When the first VM is created on the network tier, CloudStack creates the following NSX elements: + + - A DHCP Relay Networking Profile is created; associated to the segment: + - ID and name: D-A-Z-V-S-Relay + - Server IP address: A free IP on the network tier CIDR is selected. + + - A Distributed Firewall policy: + - ID and name: D-A-Z-V-S (same as the segment) + - Applied to the Group: D-A-Z-V-S + + - Distributed Firewall policy rules under the created policy: + - ID and name: D-A-Z-V-S-R where r_id is the 'id' column on the 'network_acl_items' table for all the rules on the selected Network ACL + - Action: Allow or Drop depending on the CloudStack ALC rule action (Allow or Deny) + - Service: + - Any: for the default 'Allow all' and 'Deny all' CloudStack ACLs + - In case there is a default service for the selected protocol and port then CloudStack uses the pre-existing one. In case it does not exist, then a new service is created, matching the protocol + + - After acquiring a new Public IP Address on a VPC, users can: + - Make the acquired IP address the Source NAT IP: This will replace the current NAT rule associated with the VPC Tier 1 Gateway, replacing the Translated IP for the new one. + - Enable Static NAT: a new NAT rule is created on NSX with: + - ID and name: D-A-Z-V-STATICNAT + - Action: DNAT + - Destination IP: The acquired NSX Public IP address + - Translated IP: The Guest VM IP address + + - Create Port Forwarding rules: For each CloudStack Port Forwarding rule, a new NAT rule is created on NSX, with: + - ID and name: D-A-Z-V-PF where pf_id is the 'id' column on the 'port_forwarding_rules' table, for the created rule + - Gateway: The VPC Tier 1 Gateway (with name D-A-Z-V) + - Action: DNAT + - Source IP: Any + - Destination IP: The acquired NSX Public IP address + - Destination Port: The start-end port range + - Translated IP: The guest IP of the VM + - Translated Port: The start-end port range + + - Create Load Balancing rules: There will be one load balancer created per VPC if load balancer rules are created for a specific VPC. For every subsequent load balancer rule created, additional virtual servers and server pools are added to the load balancer: + - ID and name: D-A-Z-V-LB where lb_id is the 'id' column on the 'load_balancing_rules' table, for the created rule + - Attachment: Tier 1 Gateway with ID and name: D-A-Z-V + - Virtual Server: a new Virtual Server is created, with: + - ID and name: D-A-Z-V-LB-VS + - IP address: The acquired NSX Public IP address + - Port: The public port + - Type: TCP or UDP depending on the selected protocol + - Server Pool: a new Server Pool is created, with: + - ID and name: D-A-Z-V-LB-SP + - Algorithm: Supported values: Round-robin, least connection + - Members: All the selected VMs are added as server pool members, with: + - ID and name: D-A-Z-V-VM + - IP address: The VM Guest IP address + - Port: The private port + - Active Monitor: a new Active Monitor is created, with: + - ID and name: D-A-Z-V-LB-SP---AM, where PROTO is the selected Protocol, and PORT is the selected Private Port + - Passive Monitor: default passive monitor + +.. note:: + + The following notations were used in the above section: + + - d_id: the 'id' column on the 'domain' table for the caller domain + - a_id: the 'id' column of the 'accounts' table for the owner account + - z_id: the 'id' column of the 'datacenter' table for the zone + - v_id: the 'id' column of the 'vpcs' table for the new VPC being created + - s_id: the 'id' column of the 'networks' table for the network tier being created + + +CKS on NSX +~~~~~~~~~~~ + +To enable CKS clusters on NSX networks respective default network offerings have been created for isolated and VPC tiers. + +**DefaultNSXNetworkOfferingforKubernetesService** - is the default pre-created NSX-based network offering for enabling deployment of CKS clusters on isolated networks. +**DefaultNSXVPCNetworkOfferingforKubernetesService** - is the default pre-created NSX-based network offering to enable CKS cluster deployment on VPC tiers. + + +When deploying CKS clusters, it is possible to either select a pre-existing network or allow CloudStack create a new network for the cluster during the deployment. If one chooses the latter means of cluster deployment on a NSX-based environment, it would be needed that the 'cloud.kubernetes.cluster.network.offering' global setting be updated to point to either the default offerings or the appropriate NSX-based offering created. + +All the network resources required by the CKS cluster such as load balancer, firewall rules, port forwarding rules, etc., will be created on and provided by NSX. + +Additional Notes +~~~~~~~~~~~~~~~~~ + +- Ports 67-68 need to be manually opened for network tiers of VPCs created in NSX based zones with default_deny ACL for DHCP to work as expected. +- When creating routed VPC networks in NSX-enabled zones, ensure that no 2 VPCs use the same CIDR, to prevent IP conflicts upstream (BGP). diff --git a/source/plugins/ovs-plugin.rst b/source/plugins/ovs-plugin.rst index f9493391a4..e48ca7314b 100644 --- a/source/plugins/ovs-plugin.rst +++ b/source/plugins/ovs-plugin.rst @@ -31,14 +31,14 @@ Introduction to the OVS Plugin The OVS plugin is the native SDN implementations in CloudStack, using GRE isolation method. The plugin can be -used by CloudStack to implement isolated guest networks and to provide +used by CloudStack to implement isolated guest Networks and to provide additional services like NAT, port forwarding and load balancing. Features of the OVS Plugin ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following table lists the CloudStack network services provided by +The following table lists the CloudStack Network services provided by the OVS Plugin. .. cssclass:: table-striped table-bordered table-hover @@ -101,8 +101,8 @@ KVM hypervisor: Zone Configuration ~~~~~~~~~~~~~~~~~~ -CloudStack needs to have at least one physical network with the isolation -method set to “GRE”. This network should be enabled for the Guest +CloudStack needs to have at least one physical Network with the isolation +method set to “GRE”. This Network should be enabled for the Guest traffic type. .. note:: @@ -118,7 +118,7 @@ traffic type. .. figure:: /_static/images/ovs-physical-network-gre.png :align: center - :alt: a screenshot of a physical network with the GRE isolation type + :alt: a screenshot of a physical Network with the GRE isolation type Agent Configuration @@ -127,7 +127,7 @@ Agent Configuration .. note:: Only for KVM hypervisor -- Configure network interfaces: +- Configure Network interfaces: :: @@ -187,7 +187,7 @@ Enabling the service provider ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OVS provider is disabled by default. Navigate to the "Network -Service Providers" configuration of the physical network with the GRE +Service Providers" configuration of the physical Network with the GRE isolation type. Navigate to the OVS provider and press the "Enable Provider" button. @@ -199,7 +199,7 @@ isolation type. Navigate to the OVS provider and press the Network Offerings ~~~~~~~~~~~~~~~~~ -Using the OVS plugin requires a network offering with Virtual +Using the OVS plugin requires a Network offering with Virtual Networking enabled and configured to use the OVS element. Typical use cases combine services from the Virtual Router appliance and the OVS plugin. @@ -230,20 +230,20 @@ OVS plugin. | Virtual Networking | OVS | +----------------------+-----------------+ -Table: Isolated network offering with regular services from the Virtual +Table: Isolated Network offering with regular services from the Virtual Router. .. figure:: /_static/images/ovs-network-offering.png :align: center - :alt: a screenshot of a network offering. + :alt: a screenshot of a Network offering. .. note:: - The tag in the network offering should be set to the name of the - physical network with the OVS provider. + The tag in the Network offering should be set to the name of the + physical Network with the OVS provider. -Isolated network with network services. The virtual router is still -required to provide network services like dns and dhcp. +Isolated Network with Network services. The virtual router is still +required to provide Network services like dns and dhcp. .. cssclass:: table-striped table-bordered table-hover @@ -267,7 +267,7 @@ required to provide network services like dns and dhcp. | Virtual Networking | OVS | +----------------------+-----------------+ -Table: Isolated network offering with network services +Table: Isolated Network offering with Network services Using the OVS plugin with VPC @@ -301,16 +301,16 @@ When the host agent connects to the management server, it sends the list of host list hosts id=HOST_ID filter=capabilities -Additional VM configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to enable DPDK on VM deployments, users should pass addition configuration to VMs. The required configurations are listed on the next section. Administrators can allow users to pass additional configurations to their VMs by the account scoped setting: +Additional Instance configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In order to enable DPDK on Instance deployments, users should pass addition configuration to Instances. The required configurations are listed on the next section. Administrators can allow users to pass additional configurations to their Instances by the Account scoped setting: :: enable.additional.vm.configuration Users are able to pass extra configurations as part of the 'deployVirtualMachine' or 'updateVirtualMachine' API methods. -These extra configurations are included on the resulting XML domain of the virtual machine and are also persisted on CloudStack database as details on the 'user_vm_details' table. +These extra configurations are included on the resulting XML domain of the Instance and are also persisted on CloudStack database as details on the 'user_vm_details' table. The 'deployVirtualMachine' and 'updateVirtualMachine' API methods accept a URL UTF-8 string encoded parameter 'extraconfig'. @@ -319,11 +319,11 @@ Parameter is decoded following these rules: - There could be multiple XML sections, separated by a new line - Each section can be named, setting a title ending on ':' at the first line - Double quotes instead of single quotes should be used -- Configurations are persisted as VM details, with the key: 'extraconfig-TITLE' or 'extraconfig-N' where N is a number. +- Configurations are persisted as Instance details, with the key: 'extraconfig-TITLE' or 'extraconfig-N' where N is a number. Example: -In order to pass the below extra configuration to the VM, named 'config-1' +In order to pass the below extra configuration to the Instance, named 'config-1' :: @@ -341,11 +341,11 @@ The 'extraconfig' parameter should receive the UTF-8 URL encoded string: On 'user_vm_details' table the additional configuration is persisted with key: 'extraconfig-config-1' -Additional configurations to enable DPDK on VMs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable DPDK on VM deployments: +Additional configurations to enable DPDK on Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To enable DPDK on Instance deployments: -- Set the global configuration to 'true' (as global setting or account setting) +- Set the global configuration to 'true' (as global setting or Account setting) :: @@ -374,7 +374,7 @@ To enable DPDK on VM deployments: deployVirtualMachine extraconfig=dpdk-hugepages%3A%0A%3CmemoryBacking%3E%0A%20%20%20%3Chugepages%3E%0A%20%20%20%20%3C%2Fhugepages%3E%0A%3C%2FmemoryBacking%3E%0A%0Adpdk-numa%3A%0A%3Ccpu%20mode%3D%22host-passthrough%22%3E%0A%20%20%20%3Cnuma%3E%0A%20%20%20%20%20%20%20%3Ccell%20id%3D%220%22%20cpus%3D%220%22%20memory%3D%229437184%22%20unit%3D%22KiB%22%20memAccess%3D%22shared%22%2F%3E%0A%20%20%20%3C%2Fnuma%3E%0A%3C%2Fcpu%3E%0A -- Additionally, users can pass extra configuration named 'dpdk-interface-TAG' to be included on VMs interfaces definition. Example below: +- Additionally, users can pass extra configuration named 'dpdk-interface-TAG' to be included on Instances interfaces definition. Example below: :: @@ -398,7 +398,7 @@ The vHost user mode describes a client/server model between Openvswitch along wi Applying additional configurations via service offerings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is possible to avoid passing additional configuration on each VM deployment, but setting these configurations on a service offering, and those are passed to the VM. +It is possible to avoid passing additional configuration on each Instance deployment, but setting these configurations on a service offering, and those are passed to the Instance. - To create a service offering with additional configurations, pass each key/value pair as service offering details on service offering creation, with keys starting with the "extraconfig" keyword, and each value an URL UTF-8 encoded string. - Additional configurations are stored as service offering details @@ -409,46 +409,46 @@ For example, applying DPDK additional configurations via service offering: create serviceoffering name= displaytext= serviceofferingdetails[0].key=extraconfig-dpdk-hugepages serviceofferingdetails[0].value=%3CmemoryBacking%3E%20%3Chugepages%2F%3E%20%3C%2FmemoryBacking%3E serviceofferingdetails[1].key=extraconfig-dpdk-numa serviceofferingdetails[1].value=%3Ccpu%20mode%3D%22host-passthrough%22%3E%20%3Cnuma%3E%20%3Ccell%20id%3D%220%22%20cpus%3D%220%22%20memory%3D%229437184%22%20unit%3D%22KiB%22%20memAccess%3D%22shared%22%2F%3E%20%3C%2Fnuma%3E%20%3C%2Fcpu%3E -The preferred DPDK vHost User Mode must be passed as a service offering detail, with special key name: "DPDK-VHOSTUSER". Possible values are: "client" or "server". The following table illustrates the expected behaviour on DPDK ports and VM guest interfaces. +The preferred DPDK vHost User Mode must be passed as a service offering detail, with special key name: "DPDK-VHOSTUSER". Possible values are: "client" or "server". The following table illustrates the expected behaviour on DPDK ports and Instance guest interfaces. By default, the server mode is assumed if it is not passed as a service offering detail. -+----------------------+------------------------+-------------------------+ -| DPDK vHost User Mode | OVS port creation type | VM guest interface mode | -+======================+========================+=========================+ -| server | dpdkvhostuser | client | -+----------------------+------------------------+-------------------------+ -| client | dpdkvhostuserclient | server | -+----------------------+------------------------+-------------------------+ ++----------------------+------------------------+-------------------------------+ +| DPDK vHost User Mode | OVS port creation type | Instance guest interface mode | ++======================+========================+===============================+ +| server | dpdkvhostuser | client | ++----------------------+------------------------+-------------------------------+ +| client | dpdkvhostuserclient | server | ++----------------------+------------------------+-------------------------------+ :: create serviceoffering name= displaytext= serviceofferingdetails[0].key=DPDK-VHOSTUSER serviceofferingdetails[0].value=client serviceofferingdetails[1].key=extraconfig-dpdk-hugepages serviceofferingdetails[1].value=%3CmemoryBacking%3E%20%3Chugepages%2F%3E%20%3C%2FmemoryBacking%3E serviceofferingdetails[2].key=extraconfig-dpdk-numa serviceofferingdetails[2].value=%3Ccpu%20mode%3D%22host-passthrough%22%3E%20%3Cnuma%3E%20%3Ccell%20id%3D%220%22%20cpus%3D%220%22%20memory%3D%229437184%22%20unit%3D%22KiB%22%20memAccess%3D%22shared%22%2F%3E%20%3C%2Fnuma%3E%20%3C%2Fcpu%3E -DPDK VMs live migrations -~~~~~~~~~~~~~~~~~~~~~~~~ -It is possible to perform live migrations of DPDK enabled VMs since CloudStack version 4.13. DPDK enabled VMs can be migrated between hosts in the same cluster which are both DPDK enabled. +DPDK Instances live migrations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +It is possible to perform live migrations of DPDK enabled Instances since CloudStack version 4.13. DPDK enabled Instances can be migrated between hosts in the same cluster which are both DPDK enabled. -CloudStack determinates that a VM is a DPDK enabled VM when the following conditions are met: +CloudStack determines that an Instance is a DPDK enabled VM when the following conditions are met: -- The VM is a user VM -- The VM state is Running -- The host in which the VM is running is a DPDK enabled host (i.e. host contains the 'dpdk' capability as part of its capabilities. Check `Agent configuration for DPDK support`_.) -- The VM acquires the DPDK required configurations via VM details or service offering details. DPDK required additional configurations are additional configurations with name: +- The Instance is a user Instance +- The Instance state is Running +- The host in which the Instance is running is a DPDK enabled host (i.e. host contains the 'dpdk' capability as part of its capabilities. Check `Agent configuration for DPDK support`_.) +- The Instance acquires the DPDK required configurations via Instance details or service offering details. DPDK required additional configurations are additional configurations with name: - 'extraconfig-dpdk-numa' - 'extraconfig-dpdk-hugepages' -DPDK enabled VMs can only be migrated between DPDK enabled hosts. Therefore the 'findHostsForMigration' API method excludes non-DPDK enabled hosts from the list of suitable hosts to migrate DPDK enabled VMs. +DPDK enabled Instances can only be migrated between DPDK enabled hosts. Therefore the 'findHostsForMigration' API method excludes non-DPDK enabled hosts from the list of suitable hosts to migrate DPDK enabled Instances. DPDK ports ~~~~~~~~~~ -When VM is created or started, CloudStack creates ports with DPDK support with format: "csdpdk-N" where N is a number, incremented on new ports creation. This port is set into the 'source' property of the 'interface' tag on the XML domain of the VM, prepended by the value of the OVS path set on the property: +When an Instance is created or started, CloudStack creates ports with DPDK support with format: "csdpdk-N" where N is a number, incremented on new ports creation. This port is set into the 'source' property of the 'interface' tag on the XML domain of the Instance, prepended by the value of the OVS path set on the property: :: openvswitch.dpdk.ovs.path=OVS_PATH -That would set interfaces to type 'vhostuser' and reference the ports created in the XML domain of the VMs as: +That would set interfaces to type 'vhostuser' and reference the ports created in the XML domain of the Instances as: :: diff --git a/source/plugins/quota.rst b/source/plugins/quota.rst index bf86944046..3beb0892bc 100644 --- a/source/plugins/quota.rst +++ b/source/plugins/quota.rst @@ -18,18 +18,18 @@ not exploited by attacks, careless use and program errors. To address this problem, employ the quota-enforcement service that allows resource usage within certain bounds as defined by policies and available quotas for various entities. Quota service extends the functionality of usage server to -provide a measurement for the resources used by the accounts and domains using a +provide a measurement for the resources used by the Accounts and domains using a common unit referred to as cloud currency in this document. It can be configured -to ensure that your usage won’t exceed the budget allocated to accounts/domain +to ensure that your usage won’t exceed the budget allocated to Accounts/domain in cloud currency. It will let users know how much of the cloud resources they are using. It will help the cloud admins, if they want, to ensure that a user does -not go beyond their allocated quota. Per usage cycle if an account is found to be -exceeding its quota then it is locked. Locking an account means that it will not +not go beyond their allocated quota. Per usage cycle if an Account is found to be +exceeding its quota then it is locked. Locking an Account means that it will not be able to initiate a new resource allocation request, whether it is more -storage or an additional ip. To unlock an account you need to add more credit to it. -In case you want the locking to be disabled on global or on account scope those +storage or an additional IP. To unlock an Account you need to add more credit to it. +In case you want the locking to be disabled on global or on Account scope those provisions are also provided. Needless to say quota service as well as any action -on the account is configurable. +on the Account is configurable. Enabling the Quota Service ---------------------------- @@ -46,8 +46,8 @@ set the following global configuration to true: #. quota.enable.service -By default Quota service does not lock the accounts that have exceeded the quota -usage. To enable quota service to lock accounts set the following global +By default Quota service does not lock the Accounts that have exceeded the quota +usage. To enable quota service to lock Accounts set the following global configuration to true: #. quota.enable.enforcement @@ -79,7 +79,7 @@ values. service cloudstack-management restart service cloudstack-usage restart -Once the quota service is running it will calculate the quota balance for each account. +Once the quota service is running it will calculate the quota balance for each Account. The quota usage is calculated as per the quota tariff provided by the site administrator. @@ -98,7 +98,7 @@ The following table shows all quota types for which you can specify tariff. | | | Compute-Month | +------------------+-----------------------------------+--------------------------+ | 2 | ALLOCATED\_VM | One month of allocated | -| | | VM | +| | | Instance | +------------------+-----------------------------------+--------------------------+ | 3 | IP\_ADDRESS | Quota for a month of | | | | allocated IP | @@ -125,7 +125,7 @@ The following table shows all quota types for which you can specify tariff. | 12 | PORT\_FORWARDING\_RULE | Quota for port forwarding| | | | policy month | +------------------+-----------------------------------+--------------------------+ -| 13 | NETWORK\_OFFERING | Quota for network | +| 13 | NETWORK\_OFFERING | Quota for Network | | | | Offering for a month | +------------------+-----------------------------------+--------------------------+ | 14 | VPN\_USERS | Quota for VPN usage | @@ -151,13 +151,13 @@ Quota Credits ------------- The quota credit (quotaCredit) API lets you add or remove quota currency credits to -an account. With this API you can also control the quota enforcement policy at -account level. This will enable you to have some accounts where the quota policy is +an Account. With this API you can also control the quota enforcement policy at +Account level. This will enable you to have some Accounts where the quota policy is not enforced. The overall quota enforcement is controlled by the quota.enable.enforcement global setting. In addition to above the quota API lets you can fine tune the alert generation by specifying -the quota threshold for each account. If not explictly stated, the threshold is taken as 80% +the quota threshold for each Account. If not explicitly stated, the threshold is taken as 80% of the last deposit. Quota Balance @@ -182,8 +182,8 @@ is running. Quota Alert Management ----------------------- -Quota module also provides APIs to customize various email templates that are used to -alert account owners about quota going down below threshold and quota getting over. +Quota module also provides APIs to customize various email Templates that are used to +alert Account owners about quota going down below threshold and quota getting over. All the above functionality is also available via quota UI plugin. diff --git a/source/plugins/vxlan.rst b/source/plugins/vxlan.rst index dd2c14aca8..a4726426d9 100644 --- a/source/plugins/vxlan.rst +++ b/source/plugins/vxlan.rst @@ -17,171 +17,79 @@ The VXLAN Plugin ================ -System Requirements for VXLAN ------------------------------ +General +------- +CloudStack supports VXLAN technology to enhance scalability and flexibility in networking designs. -In CloudStack 4.X.0, this plugin only supports the KVM hypervisor with the -standard linux bridge. +Using VXLAN (Virtual Extensible LAN) instead of traditional VLAN (Virtual LAN) for layer 2 isolation method offers several key benefits, especially for modern data centers and cloud networking environments that require high scalability and flexibility. -The following table lists the requirements for the hypervisor. +VXLAN overcomes the limitations of traditional VLANs by providing a highly scalable, flexible, and efficient networking solution. It enables the creation of a large number of isolated virtual networks over a common physical infrastructure, +supports better utilization of network resources through Layer 3 routing capabilities, and simplifies network management and provisioning. -.. cssclass:: table-striped table-bordered table-hover +When deploying a VXLAN-based network, there are two options to choose from: -+----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| Item | Requirement | Note | -+================+===============================================+================================================================================================================+ -| Hypervisor | KVM | OvsVifDriver is not supported by this plugin in CloudStack 4.X, use BridgeVifDriver (default). | -+----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| Linux kernel | version >= 3.7, VXLAN kernel module enabled | It is recommended to use kernel >=3.9, since Linux kernel categorizes the VXLAN driver as experimental <3.9. | -+----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| iproute2 | matches kernel version | | -+----------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ + • Multicast + • EVPN using BGP -Table: Hypervisor Requirement for VXLAN +While Multicast is the easiest to set up VXLAN isolation, EVPN offers much more control, scalability, and flexibility. Therefore, it is chosen for most VXLAN network deployments. +.. warning:: + Deploying VXLAN, especially with EVPN, requires extensive networking knowledge, which isn't covered by this documentation or CloudStack in general. + Make sure to familiarize yourself with VXLAN, BGP and EVPN before attempting to deploy this network technology. -Linux Distributions that meet the requirements ----------------------------------------------- - -The following table lists distributions which meet requirements. - -.. cssclass:: table-striped table-bordered table-hover - -+----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+ -| Distribution | Release Version | Kernel Version (Date confirmed) | Note | -+================+===================+===========================================+================================================================+ -| Ubuntu | 13.04 | 3.8.0 (2013/07/23) | | -+----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+ -| Fedora | >= 17 | 3.9.10 (2013/07/23) | Latest kernel packages are available in "update" repository. | -+----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+ -| CentOS | >= 6.5 | 2.6.32-431.3.1.el6.x86\_64 (2014/01/21) | | -+----------------+-------------------+-------------------------------------------+----------------------------------------------------------------+ - -Table: List of Linux distributions which meet the hypervisor -requirements - +System Requirements / Networking for VXLAN +------------------------------------------ -Check the capability of your system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To check the capability of your system, execute the following commands. +The following table lists the requirements for using VXLAN in your deployment: -:: - $ sudo modprobe vxlan && echo $? - # Confirm the output is "0". - # If it's non-0 value or error message, your kernel doesn't have VXLAN kernel module. ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ +| Item | Requirement | Note | ++=====================+===============================================+================================================================================================================+ +| Hypervisor | KVM | Only the BridgeVifDriver (default) is supported | ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ +| Network Card (NIC) | VXLAN offloading | A NIC with VXLAN-offloading support is recommended. For example Mellanox ConnectX-5 or Intel X710 | ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ +| IP Protocol | IPv4 or IPv6 | CloudStack is agnostic to the IP-protocol being used as underlay. Both IPv4 and IPv6 are supported | ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ +| MTU | >=1550 | VXLAN has an overhead of 50 bytes, therefore 1550 is the minimum. See the notes below | ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ +| BGP Routing | FRRouting (>=10) | BGP Routing Daemon only required for EVPN. Version >=10 is recommended | ++---------------------+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------+ - $ ip link add type vxlan help - # Confirm the output is usage of the command and that it's for VXLAN. - # If it's not, your iproute2 utility doesn't support VXLAN. +MTU size +~~~~~~~~ -Important note on MTU size -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When new vxlan interfaces are created, kernel will obtain current MTU size of the physical interface (ethX or the bridge) -and then create vxlan interface/bridge that are exactly 50 bytes smaller than the MTU on physical interface/bridge. -This means that in order to support default MTU size of 1500 bytes inside VM, your vxlan interface/bridge must also +When new VXLAN interfaces are created, kernel will obtain current MTU size of the physical interface (ethX or the bridge) +and then create VXLAN interface/bridge that are exactly 50 bytes smaller than the MTU on physical interface/bridge. +This means that in order to support default MTU size of 1500 bytes inside Instance, your VXLAN interface/bridge must also have MTU of 1500 bytes, meaning that your physical interface/bridge must have MTU of at least 1550 bytes. -In order to configure "jumbo frames" you can i.e. make physical interface/bridge with 9000 bytes MTU, then all the vxlan -interfaces will be created with MTU of 8950 bytes, and then MTU size inside VM can be set to 8950 bytes. - -Important note on max number of multicast groups (and thus VXLAN interfaces) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Default value of "net.ipv4.igmp_max_memberships" (cat /proc/sys/net/ipv4/igmp_max_memberships) is "20", which means that host can be joined to max 20 multicast groups (attach max 20 multicast IPs on the host). -Since all VXLAN (VTEP) interfaces provisioned on host are multicast-based (belong to certain multicast group, and thus has it's own multicast IP that is used as VTEP), this means that you can not provision more than 20 (working) VXLAN interfaces per host. -On Linux kernel 3.x you actually can provision more than 20, but ARP request will silently fail and cause client's networking problems -On Linux kernel 4.x you can NOT provision (start) more than 20 VXLAN interfaces and error message "No buffer space available" can be observed in Cloudstack Agent logs after provisioning required bridges and VXLAN interfaces. -Increase needed parameter to sane value (i.e. 100 or 200) as required. -If you need to operate more than 20 VMs from different client's network, this change above is required. - -Advanced: Build kernel and iproute2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Even if your system doesn't support VXLAN, you can compile the kernel -and iproute2 by yourself. The following procedure is an example for -CentOS 6.4. - - -Build kernel -^^^^^^^^^^^^ - -:: - - $ sudo yum groupinstall "Development Tools" - $ sudo yum install ncurses-devel hmaccalc zlib-devel binutils-devel elfutils-libelf-devel bc - - $ KERNEL_VERSION=3.10.4 - # Declare the kernel version you want to build. - - $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-${KERNEL_VERSION}.tar.xz - $ tar xvf linux-${KERNEL_VERSION}.tar.xz - $ cd linux-${KERNEL_VERSION} - $ cp /boot/config-`uname -r` .config - $ make oldconfig - # You may keep hitting enter and choose the default. - - $ make menuconfig - # Dig into "Device Drivers" -> "Network device support", - # then select "Virtual eXtensible Local Area Network (VXLAN)" and hit space. - # Make sure it indicates "" (build as module), then Save and Exit. - - # You may also want to check "IPv4 NAT" and its child nodes in "IP: Netfilter Configuration" - # and "IPv6 NAT" and its child nodes in "IPv6: Netfilter Configuration". - # In 3.10.4, you can find the options in - # "Networking support" -> "Networking options" - # -> "Network packet filtering framework (Netfilter)". - - $ make # -j N - # You may use -j N option to make the build process parallel and faster, - # generally N = 1 + (cores your machine have). - - $ sudo make modules_install - $ sudo make install - # You would get an error like "ERROR: modinfo: could not find module XXXX" here. - # This happens mainly due to config structure changes between kernel versions. - # You can ignore this error, until you find you need the kernel module. - # If you feel uneasy, you can go back to make menuconfig, - # find module XXXX by using '/' key, enable the module, build and install the kernel again. - - $ sudo vi /etc/grub.conf - # Make sure the new kernel isn't set as the default and the timeout is long enough, - # so you can select the new kernel during boot process. - # It's not a good idea to set the new kernel as the default until you confirm the kernel works fine. - - $ sudo reboot - # Select the new kernel during the boot process. +In order to configure "jumbo frames" you can i.e. make physical interface/bridge with 9000 bytes MTU, then all the VXLAN +interfaces will be created with MTU of 8950 bytes, and then MTU size inside Instance can be set to 8950 bytes. +In general it is recommend to use an MTU of at least 9000 bytes or larger. Most VXLAN capable network cards and switch support an MTU of up to 9216. -Build iproute2 -^^^^^^^^^^^^^^ +Using an MTU of 9216 bytes allows for using Jumbo Frames (9000) within guest networks. -:: - - $ sudo yum install db4-devel - $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git - $ cd iproute2 - $ git tag - # Find the version that matches the kernel. - # If you built kernel 3.10.4 as above, it would be v3.10.0. +VXLAN using Multicast +--------------------- +The default mode for using VXLAN is Multicast. The required configuration is described below. - $ git checkout v3.10.0 - $ ./configure - $ make # -j N - $ sudo make install +Important note on max number of multicast groups +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Default value of "net.ipv4.igmp_max_memberships" (cat /proc/sys/net/ipv4/igmp_max_memberships) is "20", which means that host can be joined to max 20 multicast groups (attach max 20 multicast IPs on the host). -.. note:: Please use rebuild kernel and tools at your own risk. +Since all VXLAN (VTEP) interfaces provisioned on host are multicast-based (belong to certain multicast group, and thus has it is own multicast IP that is used as VTEP), this means that you can not provision more than 20 (working) VXLAN interfaces per host. +Under Linux you can NOT by default provision (start) more than 20 VXLAN interfaces and the error message "No buffer space available" will appear in the Cloudstack Agent logs after provisioning the required bridges and VXLAN interfaces. -Configure CloudStack to use VXLAN Plugin -------------------------------------- +Increase the needed parameter to an appropriate value (i.e. 100 or 200) as required. -Configure hypervisor -~~~~~~~~~~~~~~~~~~~~ +If you need to operate more than 20 Instances from different client networks, the change above is required. Configure hypervisor: KVM ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -195,7 +103,7 @@ Create bridge interface with IPv4 address ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This plugin requires an IPv4 address on the KVM host to terminate and -originate VXLAN traffic. The address should be assinged to a physical +originate VXLAN traffic. The address should be assigned to a physical interface or a bridge interface bound to a physical interface. Both a private address or a public address are fine for the purpose. It is not required to be in the same subnet for all hypervisors in a zone, but @@ -207,8 +115,8 @@ differs per host, you may use a bridge to set a same name. If you would like to use a bridge name as a traffic label, you may create a bridge in this way. -Let ``cloudbr1`` be the bridge interface for the instances' private -network. +Let ``cloudbr1`` be the bridge interface for the Instances' private +Network. Configure in RHEL or CentOS @@ -267,7 +175,7 @@ When you configured ``cloudbr1`` as below, address 192.168.42.11 netmask 255.255.255.240 gateway 192.168.42.1 - dns-nameservers 8.8.8.8 8.8.4.4 + dns-nameservers 9.9.9.9 dns-domain lab.example.org # Public network @@ -299,7 +207,7 @@ you would change the configuration similar to below. address 192.168.42.11 netmask 255.255.255.240 gateway 192.168.42.1 - dns-nameservers 8.8.8.8 8.8.4.4 + dns-nameservers 9.9.9.9 dns-domain lab.example.org # Public network @@ -313,7 +221,7 @@ you would change the configuration similar to below. # Private network auto cloudbr1 iface cloudbr1 inet static - addres 192.0.2.X + address 192.0.2.X netmask 255.255.255.0 bridge_ports eth0.300 bridge_fd 5 @@ -321,91 +229,156 @@ you would change the configuration similar to below. bridge_maxwait 1 -Configure iptables to pass XVLAN packets +Configure iptables to pass VXLAN packets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Since VXLAN uses UDP packet to forward encapsulated the L2 frames, UDP/8472 port must be opened. -Configure in RHEL or CentOS -''''''''''''''''''''''''''' - -RHEL and CentOS use iptables for firewalling the system, you can open -extra ports by executing the following iptable commands: - -:: - - $ sudo iptables -I INPUT -p udp -m udp --dport 8472 -j ACCEPT - - -These iptable settings are not persistent accross reboots, we have to -save them first. - -:: - - $ sudo iptables-save > /etc/sysconfig/iptables - - -With this configuration you should be able to restart the network, -although a reboot is recommended to see if everything works properly. +Make sure that your firewall (firewalld, ufw, ...) allows UDP packets on port 8472, as an example: :: - $ sudo service network restart - $ sudo reboot + $ sudo firewall-cmd --zone=public --permanent --add-port=8472/udp + $ sudo ufw allow proto udp from any to any port 8472 -.. warning:: - Make sure you have an alternative way like IPMI or ILO to reach the machine - in case you made a configuration error and the network stops functioning! +VXLAN using EVPN +--------------------- +Using VXLAN with BGP+EVPN as underlay is more complex to set up, but does allow for more scaling and provides much more flexibility. -Configure in Ubuntu -''''''''''''''''''' +This documentation can not cover all elements of deploying BGP+EVPN in your environment. -The default firewall under Ubuntu is UFW (Uncomplicated FireWall), which -is a Python wrapper around iptables. +It is recommend to read `this blogpost `_ before you continue. -To open the required ports, execute the following commands: +The main items for using EVPN: -:: +- BGP Routing Daemon on the hypervisor +- No LACP/Bonding will be used +- The modified script (modifyvxlan-evpn.sh) is required and this might require tailoring to your situation +- BGP+EVPN capable and enabled network environment - $ sudo ufw allow proto udp from any to any port 8472 +EVPN Bash script +~~~~~~~~~~~~~~~~ +The default 'modifyvxlan.sh' script installed by CloudStack uses Multicast for VXLAN. -.. note:: - By default UFW is not enabled on Ubuntu. Executing these commands with the - firewall disabled does not enable the firewall. +A different version of this script is available which will use EVPN instead of Multicast and ships with CloudStack by default. -With this configuration you should be able to restart the network, -although a reboot is recommended to see if everything works properly. +In order to use this script create a symlink on **each** KVM hypervisor :: - - $ sudo service networking restart - $ sudo reboot - -.. warning:: - Make sure you have an alternative way like IPMI or ILO to reach the machine - in case you made a configuration error and the network stops functioning! - + $ cd /usr/share + $ ln -s cloudstack-common/scripts/vm/network/vnet/modifyvxlan-evpn.sh modifyvxlan.sh + +This script is also available in the CloudStack `GIT repository `_. + +View the contents of the script to understand its inner workings, some key items: + +- VXLAN (vtep) devices are created using 'nolearning', disabling the use of multicast +- UDP port 4789 (RFC 7348) +- IPv4 is used as underlay +- It assumes an IPv4 (/32) address is configured on the loopback interface and will be the VTEP source + +BGP routing daemon +~~~~~~~~~~~~~~~~~~~ +Using `FRRouting `_ as routing daemon is recommended, but not required. In general FRR is a BGP routing daemon with extensive EVPN support. + +Refer to the FRRouting documentation on how to install the proper packages and get started with FRR. + +A minimal configuration for FRR could look like this: + +.. code-block:: bash + + frr defaults traditional + hostname hypervisor01 + log syslog informational + no ipv6 forwarding + service integrated-vtysh-config + ! + interface ens2f0np0 + no ipv6 nd suppress-ra + ! + interface ens2f1np1 + no ipv6 nd suppress-ra + ! + interface lo + ip address 10.255.192.12/32 + ipv6 address 2001:db8:100::1/128 + ! + router bgp 4200800212 + bgp router-id 10.255.192.12 + no bgp ebgp-requires-policy + no bgp default ipv4-unicast + no bgp network import-check + neighbor uplinks peer-group + neighbor uplinks remote-as external + neighbor uplinks ebgp-multihop 255 + neighbor ens2f0np0 interface peer-group uplinks + neighbor ens2f1np1 interface peer-group uplinks + ! + address-family ipv4 unicast + network 10.255.192.12/32 + neighbor uplinks activate + neighbor uplinks next-hop-self + neighbor uplinks soft-reconfiguration inbound + neighbor uplinks route-map upstream-v4-in in + neighbor uplinks route-map upstream-v4-out out + exit-address-family + ! + address-family ipv6 unicast + network 2001:db8:100::1/128 + neighbor uplinks activate + neighbor uplinks soft-reconfiguration inbound + neighbor uplinks route-map upstream-v6-in in + neighbor uplinks route-map upstream-v6-out out + exit-address-family + ! + address-family l2vpn evpn + neighbor uplinks activate + advertise-all-vni + advertise-svi-ip + exit-address-family + + +This configuration will: + +- Establish two BGP sessions using BGP Unnumbered over the two uplinks (ens2f0np0 and ens2f1np1) +- These BGP sessions are usually established with two Top-of-Rack (ToR) switches/routers which are BGP+EVPN capable +- Enable the families ipv4, ipv6 and evpn +- Announce the IPv4 (10.255.192.12/32) and IPv6 (2001:db8:100::1/128) loopback addresses +- Advertise all VXLAN networks (VNI) detected locally on the hypervisor (vxlan network devices) +- Use ASN 4200800212 for this hypervisor (each node has it is own unique ASN) + +BGP and EVPN in the upstream network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This documentation does not cover configuring BGP and EVPN in the upstream network. + +This will differ per network and is therefore difficult to capture in this documentation. A couple of key items though: + +- Each hypervisor with establish eBGP session(s) with the Top-of-Rack router(s) in it is rack +- These Top-of-Rack devices will connect to (a) Spine router(s) +- On the Spine router(s) the VNIs will terminate and they will act as IPv4/IPv6 gateways + +The exact BGP and EVPN configuration will differ per networking vendor and thus differs per deployment. Setup zone using VXLAN -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- In almost all parts of zone setup, you can just follow the advanced zone -setup istruction in "CloudStack Installation Guide" to use this plugin. It -is not required to add a network element nor to reconfigure the network +setup instruction in "CloudStack Installation Guide" to use this plugin. It +is not required to add a Network element nor to reconfigure the Network offering. The only thing you have to do is configure the physical -network to use VXLAN as the isolation method for Guest Network. +Network to use VXLAN as the isolation method for Guest Network. -Configure the physical network -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure the physical Network +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /_static/images/vxlan-physicalnetwork.png -CloudStack needs to have one physical network for Guest Traffic with the +CloudStack needs to have one physical Network for Guest Traffic with the isolation method set to "VXLAN". .. figure:: /_static/images/vxlan-trafficlabel.png @@ -416,11 +389,11 @@ should have an IPv4 address. See ? for details. Configure the guest traffic -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /_static/images/vxlan-vniconfig.png -Specify a range of VNIs you would like to use for carrying guest network +Specify a range of VNIs you would like to use for carrying guest Network traffic. .. warning:: diff --git a/source/quickinstallationguide/qig.rst b/source/quickinstallationguide/qig.rst index 3f1cb7f1a3..5cfdab03bf 100644 --- a/source/quickinstallationguide/qig.rst +++ b/source/quickinstallationguide/qig.rst @@ -37,24 +37,23 @@ get you up and running with CloudStack with a minimum amount of trouble. .. warning:: In case you don't have physical server to "play with", you can use e.g. Oracle VirtualBox 6.1+. - The requirement is that you enable "Enable Nested VT-x/AMD-V" as the Extended Feature on the System page of the Settings of the VM. - You will want to create a VM of "Red Hat (64-bit)" type and 40+GB disk space. - You will need to have 1 NIC in your VM, bridged to the NIC of your laptop/desktop - (wifi or wired NIC, doesn't matter), and optimally to set Adapter Type="Paravirtualized Network (virtio-net)" - for somewhat better network performance (Settings of VM, Network section, Adapter1, - expand "Advanced"). Make sure the NIC on your VM is configured as promiscuous (in VirtualBox, - choose "Allow All" or just "Allow VMs" as the Promiscuous Mode), so that it can pass traffic from - CloudStack's system VMs to the gateway. Also, make sure you have allowed enough ram (6G+) and + The requirement is that you enable "Enable Nested VT-x/AMD-V" as the Extended Feature on the System page of the Settings of the Instance. + You will want to create an Instance of "Red Hat (64-bit)" type and 40+GB disk space. + You will need to have 1 NIC in your Instance, bridged to the NIC of your laptop/desktop + (bridging to a wireless adapter does frequently cause connectivity issues, so avoid it, and instead bridge to the wired adapted), + and optimally to set Adapter Type="Paravirtualized Network (virtio-net)" + for somewhat better network performance (Settings of Instance, Network section, Adapter1, + expand "Advanced"). Make sure the NIC on your Instance is configured as promiscuous (in VirtualBox, + choose "Allow All" or just "Allow Instances" as the Promiscuous Mode), so that it can pass traffic from + CloudStack's system VMs to the gateway. Also, make sure you have allowed enough ram (6G+) and enough CPU cores (3+) for demo purposes. -High level overview of the process +High-level overview of the process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This guide will focus on building a CloudStack cloud using KVM on CentOS -7.9 with NFS storage and layer-2 isolation using VLANs, -(flat home network can be used for this as well) and on a single piece of -hardware (server/VM) +This guide will focus on building a CloudStack cloud using KVM on an EL8 distro with NFS storage and layer-2 isolation using VLANs, +(flat home network can be used for this as well) and on a single piece of hardware (server/VM) KVM, or Kernel-based Virtual Machine is a virtualization technology for the Linux kernel. KVM supports native virtualization atop processors with hardware @@ -68,8 +67,11 @@ To complete this guide you'll need the following items: #. At least one computer which supports and has enabled hardware virtualization. -#. An `CentOS 7.9 minimal x86_64 install ISO, on bootable media - `_ +#. A minimal EL8 distro like + + #. Oracle Linux 8 - https://yum.oracle.com/oracle-linux-isos.html + #. Rocky Linux 8 - https://rockylinux.org/download + #. AlmaLinux OS 8 - https://almalinux.org/get-almalinux/ #. A /24 network with the gateway being at (e.g.) xxx.xxx.xxx.1, no DHCP is needed on this network and none of the computers running CloudStack will have a @@ -86,10 +88,9 @@ CloudStack. We will go over the steps to prepare now. Operating System ~~~~~~~~~~~~~~~~ -Using the CentOS 7.9.2009 minmal x86_64 install ISO, you'll need to install -CentOS 7 on your hardware. The defaults will generally be acceptable for this +Install preferred EL8 distro on your hardware. The defaults will generally be acceptable for this installation - but make sure to configure IP address/parameters so that you can later install needed -packages from internet. Later, we will change the network configuration as needed. +packages from the internet. Later, we will change the Network configuration as needed. Once this installation is complete, you'll want to gain access to your server - through SSH. @@ -97,85 +98,52 @@ server - through SSH. It is always wise to update the system before starting: .. parsed-literal:: - # yum -y upgrade + # dnf -y upgrade .. _conf-network: -Configuring the network +Configuring the Network ^^^^^^^^^^^^^^^^^^^^^^^ -Before going any further, make sure that "bridge-utils" and "net-tools" are installed and available: - -.. parsed-literal:: - # yum install bridge-utils net-tools -y +Starting with EL8, we must use the Network Manager to configure all network interfaces +(instead of using the network-scripts we have used for so many years). -Connecting via the console or SSH, you should login as root. We will start by creating -the bridge that Cloudstack will use for networking. Create and open -/etc/sysconfig/network-scripts/ifcfg-cloudbr0 and add the following settings: +We will start by creating the bridge that Cloudstack will use for networking. +To avoid remote (ssh) disconnections, you should be logging to the server locally, +via console/physical screen (or save the commands below as a script and then run it +via remote ssh session) .. note:: IP Addressing - Throughout this document we are assuming that you will have a /24 network for your CloudStack implementation. This can be any RFC 1918 - network. However, we are assuming that you will match the machine address + Network. However, we are assuming that you will match the machine address that we are using. Thus we may use 172.16.10.2 and because you might be using e.g. 192.168.55.0/24 network you would use 192.168.55.2. Another example would be if you are using i.e. VirtualBox on your local home network on 192.168.1.0/24 network - - in this case you can use a single free IP address from your home range (VirtualBox NIC for this VM + in this case you can use a single free IP address from your home range (VirtualBox NIC for this Instance should be in bridged mode for correct functioning) :: - DEVICE=cloudbr0 - TYPE=Bridge - ONBOOT=yes - BOOTPROTO=static - IPV6INIT=no - IPV6_AUTOCONF=no - DELAY=5 - IPADDR=172.16.10.2 #(or e.g. 192.168.1.2) - GATEWAY=172.16.10.1 #(or e.g. 192.168.1.1 - this would be your physical/home router) - NETMASK=255.255.255.0 - DNS1=8.8.8.8 - DNS2=8.8.4.4 - STP=yes - USERCTL=no - NM_CONTROLLED=no - -Save the configuration and exit. We will then edit the NIC so that it -makes use of this bridge. - -Open the configuration file of your NIC (e.g. /etc/sysconfig/network-scripts/ifcfg-eth0) -and edit it as follows: + #create an "empty” bridge, add eth0 to the bridge, set static IP and reactivate the whole configuration + nmcli connection add type bridge con-name cloudbr0 ifname cloudbr0 + nmcli connection modify eth0 master cloudbr0 + nmcli connection up eth0 + nmcli connection modify cloudbr0 ipv4.addresses '172.16.10.2/24' ipv4.gateway '172.16.10.1' ipv4.dns '8.8.8.8' ipv4.method manual && nmcli connection up cloudbr0 .. note:: Interface name (eth0) used as example only. Replace eth0 with your default ethernet interface name. -.. parsed-literal:: - TYPE=Ethernet - BOOTPROTO=none - DEFROUTE=yes - NAME=eth0 - DEVICE=eth0 - ONBOOT=yes - BRIDGE=cloudbr0 - -.. note:: - If your physical nic (eth0 in the case of our example) has already been - setup before following this guide, make sure that there is no duplication - between IP configuration of /etc/config/network-scripts/ifcfg-cloudbr0 and - /etc/sysconfig/network-scripts/ifcfg-eth0 which will cause a failure that - would prevent the network from starting. Basically, IP configuration - of eth0 should be moved to the bridge and eth0 will be added to the bridge. +Optionally, we can install the net-tools: +.. parsed-literal:: + # dnf install net-tools -y -Now that we have the configuration files properly set up, we need to run a few -commands to start up the network: +Now that we have the configuration files properly set up, let's reboot: .. parsed-literal:: - # systemctl disable NetworkManager; systemctl stop NetworkManager - # systemctl enable network # reboot .. _conf-hostname: @@ -197,23 +165,19 @@ At this point it will likely return: localhost -To rectify this situation - we'll set the hostname by editing the /etc/hosts -file so that it follows a similar format to this example (remember to replace -the IP with your IP which might be e.g. 192.168.1.2): +To rectify this situation - we'll set the hostname so that it follows a similar format to this example: .. parsed-literal:: - 127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 - ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 - 172.16.10.2 srvr1.cloud.priv + hostnamectl set-hostname server.local --static -After you've modified that file, go ahead and restart the network using: +After you've modified that file, go ahead and reboot: .. parsed-literal:: - # systemctl restart network + # reboot -Now recheck with the +Now recheck the hostname with the .. parsed-literal:: @@ -227,9 +191,10 @@ and ensure that it returns a FQDN response SELinux ^^^^^^^ -At the moment, for CloudStack to work properly SELinux must be set to -permissive or disabled. We want to both configure this for future boots and modify it in -the current running system. +In an ideal environment, selinux should be set to enforcing and the necessary +selinux policies are created to allow the services to run. For this guide, +we will set selinux to permissive mode. This will allow us to install and +configure the services without having to worry about selinux policies. To configure SELinux to be permissive in the running system we need to run the following command: @@ -257,8 +222,8 @@ To ensure that it remains in that state we need to configure the file .. _conf-ntp: -NTP -^^^ +NTP (Chrony) +^^^^^^^^^^^^ NTP configuration is a necessity for keeping all of the clocks in your cloud servers in sync. However, NTP is not installed by default. So we'll install @@ -266,15 +231,15 @@ and and configure NTP at this stage. Installation is accomplished as follows: .. parsed-literal:: - # yum -y install ntp + # dnf -y install chrony The actual default configuration is fine for our purposes, so we merely need to enable it and set it to start on boot as follows: .. parsed-literal:: - # systemctl enable ntpd - # systemctl start ntpd + # systemctl enable chronyd + # systemctl start chronyd .. _qigconf-pkg-repo: @@ -313,7 +278,7 @@ start out by installing nfs-utils. .. parsed-literal:: - # yum -y install nfs-utils + # dnf -y install nfs-utils We now need to configure NFS to serve up two different shares. This is handled in the /etc/exports file. You should ensure that it has the following content: @@ -332,31 +297,17 @@ appropriately on them with the following commands: # mkdir -p /export/primary # mkdir /export/secondary -CentOS 7.x releases use NFSv4 by default. NFSv4 requires that domain setting -matches on all clients. In our case, the domain is cloud.priv, so ensure that -the domain setting in /etc/idmapd.conf is uncommented and set as follows: +NFSv4 requires that domain setting matches on all clients. In our case, the +domain is "local", so ensure that the domain setting in /etc/idmapd.conf is uncommented and set as follows: .. parsed-literal:: - Domain = cloud.priv - -Now you'll need to add the configuration values at the bottom in the file -/etc/sysconfig/nfs (or merely uncomment and set them) - -.. parsed-literal:: - - LOCKD_TCPPORT=32803 - LOCKD_UDPPORT=32769 - MOUNTD_PORT=892 - RQUOTAD_PORT=875 - STATD_PORT=662 - STATD_OUTGOING_PORT=2020 + Domain = local For simplicity, we need to disable the firewall, so that it will not block connections. .. note:: - Configuration of the firewall on CentOS7 is beyond the purview of this - guide. + Configuration of the firewall is beyond the purview of this guide. To do so, simply use the following two commands: @@ -371,9 +322,9 @@ it on the host by executing the following commands: .. parsed-literal:: # systemctl enable rpcbind - # systemctl enable nfs + # systemctl enable nfs-server # systemctl start rpcbind - # systemctl start nfs + # systemctl start nfs-server Management Server Installation @@ -388,23 +339,13 @@ Database Installation and Configuration We'll start with installing MySQL and configuring some options to ensure it runs well with CloudStack. -First, as CentOS 7 no longer provides the MySQL binaries, we need to add a MySQL community repository, -that will provide MySQL Server (and the Python MySQL connector later) : - -.. parsed-literal:: - # yum -y install wget - # wget http://repo.mysql.com/mysql-community-release-el7-5.noarch.rpm - # rpm -ivh mysql-community-release-el7-5.noarch.rpm - -Install by running the following command: - .. parsed-literal:: - # yum -y install mysql-server + # dnf -y install mysql-server -This should install MySQL 5.x, as of the time of writing this guide. +This should install MySQL 8.x, as of the time of writing this guide. With MySQL now installed we need to make a few configuration changes to -/etc/my.cnf. Specifically we need to add the following options to the [mysqld] +/etc/my.cnf.d/mysql-server.cnf. Specifically, we need to add the following options to the [mysqld] section: .. parsed-literal:: @@ -412,21 +353,9 @@ section: innodb_rollback_on_timeout=1 innodb_lock_wait_timeout=600 max_connections=350 - log-bin=mysql-bin - binlog-format = 'ROW' + log_bin=mysql-bin + binlog_format=ROW -.. note:: - - For Ubuntu 16.04 and later, make sure you specify a ``server-id`` in your ``.cnf`` file for binary logging. Set the ``server-id`` according to your database setup. - -.. parsed-literal:: - - server-id=source-01 - innodb_rollback_on_timeout=1 - innodb_lock_wait_timeout=600 - max_connections=350 - log-bin=mysql-bin - binlog-format = 'ROW' Now that MySQL is properly configured we can start it and configure it to start on boot as follows: @@ -436,19 +365,6 @@ start on boot as follows: # systemctl enable mysqld # systemctl start mysqld - -MySQL Connector Installation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Install Python MySQL connector from the MySQL community repository (which we've added previously): - -.. parsed-literal:: - - # yum -y install mysql-connector-python - -Please note that the previously required ``mysql-connector-java`` library is now bundled with CloudStack -Management server and is no more required to be installed separately. - Installation ~~~~~~~~~~~~ @@ -457,17 +373,17 @@ following command: .. parsed-literal:: - # yum -y install cloudstack-management + # dnf -y install cloudstack-management -CloudStack |version| requires Java 11 JRE. Installing the management server -will automatically install Java 11, but it's good to explicitly confirm that the Java 11 +CloudStack |version| requires Java 17 JRE. Installing the management server +will automatically install Java 17, but it's good to explicitly confirm that Java 17 is the selected/active one (in case you had a previous Java version already installed): .. parsed-literal:: $ alternatives --config java -Make sure that Java 11 is the chosen one. +Make sure that Java 17 is selected. With the application itself installed we can now setup the database, we'll do that with the following command and options: @@ -486,23 +402,46 @@ up the management server by issuing the following command: # cloudstack-setup-management + .. note:: + Since 4.23.0, the ``cloudstack-setup-management`` command + can download SystemVM templates on demand when they are not present. -System Template Setup -~~~~~~~~~~~~~~~~~~~~~ + Use the ``--systemvm-templates`` argument to specify which templates to + download. Valid values are ``all``, ``kvm-aarch64``, ``kvm-x86_64``, + ``xenserver``, and ``vmware``. A comma-separated list combining any of + these identifiers can also be supplied (for example + ``kvm-x86_64,xenserver``). If not specified, ``kvm-x86_64`` template + will be downloaded by default. -CloudStack uses a number of system VMs to provide functionality for accessing -the console of virtual machines, providing various networking services, and -managing various aspects of storage. + For offline environments, provide a custom repository URL with the + ``--systemvm-templates-repository`` argument so the installer can fetch + templates from an internal mirror. -We need to download the systemVM template and deploy that to the secondary storage. -We will use the local path (/export/secondary) since we are already on the NFS server itself, -but otherwise you would need to mount your Secondary Storage to a temporary mount point, and use -that mount point instead of the /export/secondary path. -Execute the followint script: +System VM Template Setup +~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack relies on several System VMs (for example SSVM and CPVM) to +provide console access, networking services and storage management. Manual +installation of System VM templates is not required in recent CloudStack +releases. Since 4.16.0, automatic seeding of System VM templates has been +supported; the ``cloudstack-management`` package historically included bundled +templates and the Management Server seeded them to secondary storage during +startup or when a secondary store was added to a zone. Starting with 4.23.0, +CloudStack supports on-demand downloading of System VM templates when they +are not present locally or bundled with the package. + +Templates are typically obtained in two ways: during initial setup via +``cloudstack-setup-management`` or automatically at Management +Server startup and secondary store addition (the Management Server +will attempt to download and seed any missing templates). + +When automated mechanisms are unsuitable, templates can be downloaded and +deployed to secondary storage using the helper script. On the secondary +storage host (or a temporary mount of the secondary store) run:: .. parsed-literal:: - + /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt \ -m /export/secondary \ -u |sysvm64-url-kvm| \ @@ -541,12 +480,11 @@ Installation ~~~~~~~~~~~~ Installation of the KVM agent is trivial with just a single command, but -afterwards we'll need to configure a few things. We need to install the EPEL repository also. +afterwards we'll need to configure a few things. .. parsed-literal:: - # yum -y install epel-release - # yum -y install cloudstack-agent + # dnf -y install cloudstack-agent KVM Configuration @@ -569,17 +507,17 @@ and ensuring the following line is present and uncommented. Libvirt Configuration ^^^^^^^^^^^^^^^^^^^^^^^ -CloudStack uses libvirt for managing virtual machines. Therefore it is vital +CloudStack uses libvirt for managing Instances. Therefore it is vital that libvirt is configured correctly. Libvirt is a dependency of cloud-agent and should already be installed. #. Even though we are using a single host, the following steps are recommended - to get faimilar with the general requirements. - In order to have live migration working libvirt has to listen for unsecured + to get familiar with the general requirements. + In order to have live migration working libvirt has to listen for unsecured TCP connections. We also need to turn off libvirts attempt to use Multicast DNS advertising. Both of these settings are in /etc/libvirt/libvirtd.conf - Set the following paramaters: + Set the following parameters: :: @@ -598,6 +536,12 @@ and should already be installed. #LIBVIRTD_ARGS="--listen" +# As of EL8, we'll have to do the socket masking: + + .. parsed-literal:: + + # systemctl mask libvirtd.socket libvirtd-ro.socket libvirtd-admin.socket libvirtd-tls.socket libvirtd-tcp.socket + #. Restart libvirt .. parsed-literal:: @@ -658,12 +602,12 @@ Zone Details On this page, we enter where our DNS servers are located. CloudStack distinguishes between internal and public DNS. Internal DNS is assumed to be capable of resolving internal-only hostnames, such as your -NFS server’s DNS name. Public DNS is provided to the guest VMs to resolve +NFS server’s DNS name. Public DNS is provided to the guest Instances to resolve public IP addresses. You can enter the same DNS server for both types, but if you do so, you must make sure that both internal and public IP addresses can route to the DNS server. In our specific case we will not use any names for resources internally, and we will indeed set them to look to the same -external resource so as to not add a namerserver setup to our list of +external resource so as to not add a nameserver setup to our list of requirements. #. Name - we will set this to the ever-descriptive 'Zone1' for our cloud. @@ -718,7 +662,7 @@ Pod Configuration Here we will configure a range for Cloudstack's internal management traffic - CloudStack will assign IPs from this range to system VMs. This will also be part of our local network (i.e. different part of your local home network, from .21 to .30), with the rest of the IP parameters -(netmaks/gateway) being the same as used for the Public Traffic. +(netmask/gateway) being the same as used for the Public Traffic. #. Pod Name - We'll use ``Pod1`` for our cloud. @@ -730,12 +674,15 @@ will assign IPs from this range to system VMs. This will also be part of our loc #. End Reserved system IP - we will use ``172.16.10.30`` # (or e.g. 192.168.1.30) +.. note:: + * The network described above must be a subnet of the management network. + Click "Next" to continue. Guest Traffic ~~~~~~~~~~~~~ -Next we will configure a range of VLAN IDs for our guest VMs. +Next we will configure a range of VLAN IDs for our Guest Instances. A range of ``100`` - ``200`` would suffice. @@ -810,8 +757,9 @@ That's it, you are done with installation of your Apache CloudStack demo cloud. To check the health of your CloudStack installation, go to Infrastructure --> System VMs and refresh the UI from time to time - you should see “S-1-VM” and “V-2-VM” system VMs (SSVM and CPVM) in State=Running and Agent State=Up -After that you can go to Images --> Templates, click on the built-in template named "CentOS 5.5(64-bit) no GUI (KVM)", + +After that you can go to Images --> Templates, click on the built-in Template named "CentOS 5.5(64-bit) no GUI (KVM)", then click on "Zones" tab - and observe how the Status is moving from a few percents downloaded up to fully downloaded, after which the Status will show as "Download Complete" and "Ready" column will say "Yes". -After this is done, you will be able to deploy a VM from this template. +After this is done, you will be able to deploy an Instance from this Template. diff --git a/source/releasenotes/about.rst b/source/releasenotes/about.rst index 1889d6f45f..89c68b9ea9 100644 --- a/source/releasenotes/about.rst +++ b/source/releasenotes/about.rst @@ -17,33 +17,38 @@ What's New in |release| ======================= -Apache CloudStack 4.16.0.0 is a 4.16 LTS release with over 22 major new -features, and over 244 enhancements and fixes since 4.15. Highlights include: - -• System VM Template improvements -• CKS Support for Cluster Autoscaling -• Dell EMC VxFlex integration -• Linstor Volume Plugin integration -• Support for OpenSuse -• Support for Rocky Linux -• Granular control of dynamic scaling of VM's CPU/RAM -• Comments in the UI -• Resource Icons -• Bulk actions through the UI -• UI for VM Ingestion -• L2 Networks Persistent modern -• Script cloudstack-setup-databases improvement -• Add mac learning mode in network offering -• API-call to declare host as Degraded -• New API endpoint to update pod management network IP range -• Add New API endpoint: UpdateVlanIpRange +Apache CloudStack |release| is a 4.22 LTS release with 10 new features, +around 15 improvements and more than 140 bug fixes since the 4.21.0.0 release. +Some of the highlights include: -The full list of new features can be found in the project release notes at -https://docs.cloudstack.apache.org/en/4.16.0.0/releasenotes/changes.html +Enhanced Backup and Disaster Recovery +SSL Offloading for Load Balancers +Baremetal/MaaS Extension +CSI Driver for CKS +Console Access for Proxmox in Extensions Framework +VMware-to-KVM Migration Enhancements +Snapshot/Backup Schedule Listing +Per-Zone Console Proxy Configuration +Direct Volume Migration within Cluster +Persistent KVM Domains +Support for userdata on System VMs +EL10 & OpenSUSE 15.6 Platform Support +Stronger Checksum Algorithm (SHA-512) +Enable KVM volume and VM snapshot by default +Support xz format for template registration +Support for shared Filesystem on Config Drive Networks + +Known Issues +------------ -Legacy UI Removal Notice -======================== +• Starting 4.21 VM snapshots are supported for instances on KVM hosts. However, volume snapshots and VM snapshots cannot coexist. + Restoring a volume snapshot will remove any existing VM snapshots and may lead to data loss. + There is a UI issue where error messages in such scenarios may not clearly indicate the problem. -The legacy UI was deprecated with Apache CloudStack 4.15 release and -with 4.16 release the legacy UI has been removed. Users are encouraged to -implement a migration path in their production environments. +• When managing and unmanaging UEFI-based VMs on KVM hosts, migration of such VMs may fail in certain scenarios. + This typically occurs when a VM that was unmanaged and later re-imported is started on a different host and then + migrated back to its original host. The migration fails because the VM domain still exists on the original host, + resulting in a conflict. As a workaround, manually remove the old domain from the original host before attempting the migration again. + +The full list of new features can be found in the project release notes at +https://docs.cloudstack.apache.org/en/4.22.0.0/releasenotes/changes.html diff --git a/source/releasenotes/api-changes.rst b/source/releasenotes/api-changes.rst index 9c7df6786d..e32a7d099f 100644 --- a/source/releasenotes/api-changes.rst +++ b/source/releasenotes/api-changes.rst @@ -13,46 +13,10 @@ specific language governing permissions and limitations under the License. -API Changes Introduced in 4.16.0.0 -=================================== -For the complete list of API commands and params consult the `CloudStack Apidocs`_. - -New API Commands ----------------- - -.. cssclass:: table-striped table-bordered table-hover - -+---------------------------------------------+--------------------------------------------------------------------------------+ -| Name | Description | -+=============================================+================================================================================+ -| ``listResourceIcon`` | Lists the resource icon for the specified resource(s) | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updatePodManagementNetworkIpRange`` | Updates a management network IP range. Only allowed when no IPs are allocated. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``deleteResourceIcon`` | deletes the resource icon from the specified resource(s) | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateBackupOffering`` | Updates a backup offering. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateStorageCapabilities`` | Syncs capabilities of storage pools | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``uploadResourceIcon`` | Uploads an icon for the specified resource(s) | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVlanIpRange`` | Updates a VLAN IP range. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``declareHostAsDegraded`` | Declare host as 'Degraded'. Host must be on 'Disconnected' or 'Alert' state. | -| | The ADMIN must be sure that there are no VMs running on the respective host | -| | otherwise this command might corrupted VMs that were running on the 'Degraded' | -| | host. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateAnnotationVisibility`` | update an annotation visibility. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``cancelHostAsDegraded`` | Cancel host status from 'Degraded'. Host will transit back to status | -| | 'Enabled'. | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``syncStoragePool`` | Sync storage pool with management server (currently supported for Datastore | -| | Cluster in VMware and syncs the datastores in it) | -+---------------------------------------------+--------------------------------------------------------------------------------+ +API Changes Introduced in 4.22.0.0 +================================== +For the complete list of API commands and params consult the `CloudStack Apidocs`_. Parameters Changed API Commands ------------------------------- @@ -62,1666 +26,381 @@ Parameters Changed API Commands +---------------------------------------------+--------------------------------------------------------------------------------+ | Name | Description | +=============================================+================================================================================+ -| ``createVPCOffering`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``enable`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``ldapCreateAccount`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createPod`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ipranges(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``copyIso`` | **Response:** | +| ``listVsphereStoragePolicyCompatiblePools`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVirtualMachinesMetrics`` | **Request:** | +| ``removeNodesFromKubernetesCluster`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``showicon`` (optional) | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``rebootSystemVm`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``forced`` (optional) | -| | | -| | **Response:** | +| ``updateHost`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | +| | - ``cleanupexternaldetails`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listNetworks`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | +| ``createBackupSchedule`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``isbackupvmexpunged`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``registerSSHKeyPair`` | **Response:** | +| ``addNodesToKubernetesCluster`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``id`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``restoreVirtualMachine`` | **Response:** | +| ``listKubernetesClusters`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``uploadVolume`` | **Response:** | +| ``listCapabilities`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``supportsstoragesnapshot`` | +| | - ``additionalconfigenabled`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``destroySystemVm`` | **Response:** | +| ``createSnapshotPolicy`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | +| | - ``volumename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listAnnotations`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``annotationfilter`` (optional) | -| | - ``userid`` (optional) | -| | | -| | **Response:** | +| ``listStoragePools`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``adminsonly`` | -| | - ``entityname`` | -| | - ``username`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``scaleSystemVm`` | **Response:** | +| ``deleteLdapConfiguration`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVpnCustomerGateway`` | **Request:** | +| | - ``id`` (optional) | | | | -| | *New Parameters:* | +| | *Changed Parameters:* | | | | -| | - ``ikeversion`` (optional) | -| | - ``splitconnections`` (optional) | +| | - ``hostname`` was 'required' and is now 'optional' | | | | | | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``lockAccount`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listProjectRolePermissions`` | **Response:** | -| | | -| | *New Parameters:* | -| | | | | - ``id`` | -| | - ``projectid`` | -| | - ``projectroleid`` | -| | - ``projectrolename`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``displaytext`` | -| | - ``success`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``changeServiceForVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listTemplates`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``rebootVirtualMachine`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``forced`` (optional) | -| | | -| | **Response:** | +| ``listBackups`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``isbackupvmexpunged`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``stopSystemVm`` | **Response:** | +| ``upgradeKubernetesCluster`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVPC`` | **Response:** | +| ``listBackupProviderOfferings`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``network`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``network(*)`` | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createNetworkOffering`` | **Request:** | +| ``importBackupOffering`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``enable`` (optional) | -| | | -| | *Changed Parameters:* | -| | | -| | - ``supportedservices`` was 'required' and is now 'optional' | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVmNicIp`` | **Response:** | +| ``updateBackupSchedule`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``isbackupvmexpunged`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listPods`` | **Response:** | +| ``updateStoragePool`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``ipranges(*)`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``resetVpnConnection`` | **Response:** | +| ``listBackupRepositories`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listKubernetesClusters`` | **Response:** | +| ``listNetworks`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``autoscalingenabled`` | -| | - ``controlnodes`` | -| | - ``maxsize`` | -| | - ``minsize`` | +| | - ``name`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``scaleKubernetesCluster`` | **Request:** | +| ``listSnapshotPolicies`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``autoscalingenabled`` (optional) | -| | - ``maxsize`` (optional) | -| | - ``minsize`` (optional) | -| | - ``nodeids`` (optional) | +| | - ``account`` (optional) | +| | - ``domainid`` (optional) | +| | - ``isrecursive`` (optional) | +| | - ``listall`` (optional) | +| | - ``projectid`` (optional) | | | | | | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``autoscalingenabled`` | -| | - ``controlnodes`` | -| | - ``maxsize`` | -| | - ``minsize`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listCapabilities`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``defaultuipagesize`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``destroyVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | +| | - ``volumename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateDomain`` | **Response:** | +| ``listLdapConfigurations`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``domaindetails`` | -| | - ``icon`` | +| | - ``id`` (optional) | | | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listSystemVms`` | **Response:** | +| | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | +| | - ``id`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createProject`` | **Response:** | +| ``listBackupOfferings`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``detachVolume`` | **Response:** | +| ``scaleKubernetesCluster`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``supportsstoragesnapshot`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``markDefaultZoneForAccount`` | **Response:** | +| ``addBackupRepository`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | +| | - ``crosszoneinstancecreation`` (optional) | | | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``changeServiceForSystemVm`` | **Response:** | +| | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``isdynamicallyscalable`` | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``rebootRouter`` | **Request:** | +| ``assignCertToLoadBalancer`` | **Request:** | | | | | | *New Parameters:* | | | | | | - ``forced`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``addNicToVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateIso`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateDefaultNicForVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``prepareTemplate`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createDomain`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``domaindetails`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``restartNetwork`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``displaytext`` | -| | - ``success`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``id`` | -| | - ``account`` | -| | - ``allocated`` | -| | - ``associatednetworkid`` | -| | - ``associatednetworkname`` | -| | - ``domain`` | -| | - ``domainid`` | -| | - ``fordisplay`` | -| | - ``forvirtualnetwork`` | -| | - ``ipaddress`` | -| | - ``isportable`` | -| | - ``issourcenat`` | -| | - ``isstaticnat`` | -| | - ``issystem`` | -| | - ``networkid`` | -| | - ``networkname`` | -| | - ``physicalnetworkid`` | -| | - ``project`` | -| | - ``projectid`` | -| | - ``purpose`` | -| | - ``state`` | -| | - ``virtualmachinedisplayname`` | -| | - ``virtualmachineid`` | -| | - ``virtualmachinename`` | -| | - ``vlanid`` | -| | - ``vlanname`` | -| | - ``vmipaddress`` | -| | - ``vpcid`` | -| | - ``vpcname`` | -| | - ``zoneid`` | -| | - ``zonename`` | -| | - ``tags(*)`` | -| | - ``jobid`` | -| | - ``jobstatus`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createServiceOffering`` | **Request:** | +| ``unmanageVirtualMachine`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``dynamicscalingenabled`` (optional) | +| | - ``forced`` (optional) | +| | - ``hostid`` (optional) | | | | | | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``dynamicscalingenabled`` | -| | - ``storagetags`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``tags`` | +| | - ``hostid`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``copyTemplate`` | **Response:** | +| ``updateBackupOffering`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | +| | - ``crosszoneinstancecreation`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listNiciraNvpDeviceNetworks`` | **Response:** | +| ``updateStorageCapabilities`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``assignVirtualMachine`` | **Response:** | +| ``listVirtualMachinesUsageHistory`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``stats(*)`` | | | | | | *Removed Parameters:* | | | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``resizeVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateTemplate`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVpnConnection`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listPaloAltoFirewallNetworks`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``stats`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVolume`` | **Request:** | +| ``createKubernetesCluster`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``name`` (optional) | +| | - ``enablecsi`` (optional) | | | | | | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateAccount`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVirtualMachine`` | **Response:** | +| ``addLdapConfiguration`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``id`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listDomains`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | +| ``getUploadParamsForTemplate`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``domaindetails`` | -| | - ``icon`` | +| | - ``templatetype`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``disableAccount`` | **Response:** | +| ``syncStoragePool`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateNetwork`` | **Response:** | +| ``listInfrastructure`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``backuprepositories`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateVirtualMachine`` | **Request:** | +| ``findStoragePoolsForMigration`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``autoselect`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createTemplate`` | **Response:** | +| ``createStoragePool`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``resetPasswordForVirtualMachine`` | **Response:** | +| ``listSystemVmsUsageHistory`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``stats(*)`` | | | | | | *Removed Parameters:* | | | | -| | - ``readonlyuidetails`` | +| | - ``stats`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVpnCustomerGateways`` | **Response:** | +| ``enableStorageMaintenance`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``resetSSHKeyForVirtualMachine`` | **Response:** | +| ``cancelStorageMaintenance`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``addKubernetesSupportedVersion`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsautoscaling`` | +| | - ``capacitybytes`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createVPC`` | **Response:** | +| ``updateSnapshotPolicy`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``network`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``network(*)`` | +| | - ``volumename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listSrxFirewallNetworks`` | **Response:** | +| ``updateLoadBalancerRule`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``cidrlist`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateKubernetesSupportedVersion`` | **Response:** | +| ``startKubernetesCluster`` | **Response:** | | | | | | *New Parameters:* | | | | -| | - ``supportsautoscaling`` | +| | - ``csienabled`` | +| | - ``templatename`` | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``detachIso`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``forced`` (optional) | -| | | -| | **Response:** | +| ``listBackupSchedule`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | +| | - ``account`` (optional) | +| | - ``domainid`` (optional) | +| | - ``id`` (optional) | +| | - ``isrecursive`` (optional) | +| | - ``listall`` (optional) | +| | - ``projectid`` (optional) | | | | -| | *Removed Parameters:* | +| | *Changed Parameters:* | | | | -| | - ``readonlyuidetails`` | +| | - ``virtualmachineid`` was 'required' and is now 'optional' | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVirtualMachines`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``clusterid`` (optional) | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | +| ``importVm`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | +| | - ``extraparams`` (optional) | +| | - ``forceconverttopool`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``upgradeKubernetesCluster`` | **Response:** | +| ``updateServiceOffering`` | **Request:** | | | | | | *New Parameters:* | | | | -| | - ``autoscalingenabled`` | -| | - ``controlnodes`` | -| | - ``maxsize`` | -| | - ``minsize`` | +| | - ``cleanupexternaldetails`` (optional) | | | | +---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listProjects`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createAccount`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``revertToVMSnapshot`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``addAnnotation`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``adminsonly`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``adminsonly`` | -| | - ``entityname`` | -| | - ``username`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``registerIso`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``deployVirtualMachine`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``dynamicscalingenabled`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateZone`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listProjectAccounts`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createDiskOffering`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``details`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVolumes`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``lockUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createNetwork`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``routerip`` (optional) | -| | - ``routeripv6`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVPCs`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``network`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``network(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateVirtualMachineWithVolume`` | **Request:** | -| | | -| | *Changed Parameters:* | -| | | -| | - ``hostid`` was 'required' and is now 'optional' | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``restartVPC`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``success`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``id`` | -| | - ``account`` | -| | - ``cidr`` | -| | - ``created`` | -| | - ``distributedvpcrouter`` | -| | - ``domain`` | -| | - ``domainid`` | -| | - ``fordisplay`` | -| | - ``name`` | -| | - ``networkdomain`` | -| | - ``project`` | -| | - ``projectid`` | -| | - ``redundantvpcrouter`` | -| | - ``regionlevelvpc`` | -| | - ``restartrequired`` | -| | - ``state`` | -| | - ``vpcofferingid`` | -| | - ``vpcofferingname`` | -| | - ``zoneid`` | -| | - ``zonename`` | -| | - ``network(*)`` | -| | - ``service(*)`` | -| | - ``tags(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``attachVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``addHost`` | **Request:** | -| | | -| | *Changed Parameters:* | -| | | -| | - ``password`` was 'required' and is now 'optional' | -| | - ``username`` was 'required' and is now 'optional' | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateProject`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listUsers`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVpnConnections`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``disableUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listIsos`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listZones`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listNetscalerLoadBalancerNetworks`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``startSystemVm`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``isdynamicallyscalable`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createKubernetesCluster`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``controlnodes`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``autoscalingenabled`` | -| | - ``controlnodes`` | -| | - ``maxsize`` | -| | - ``minsize`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateVMAffinityGroup`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``resetApiLimit`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``displaytext`` | -| | - ``success`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | - ``accountid`` | -| | - ``apiAllowed`` | -| | - ``apiIssued`` | -| | - ``expireAfter`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateVPC`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``network`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``network(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``getUploadParamsForTemplate`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``deployasis`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``recoverVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateSystemVm`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``autoselect`` (optional) | -| | - ``storageid`` (optional) | -| | | -| | *Changed Parameters:* | -| | | -| | - ``hostid`` was 'required' and is now 'optional' | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``isdynamicallyscalable`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listRouters`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``healthchecksfailed`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createVpnConnection`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listBrocadeVcsDeviceNetworks`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listKubernetesSupportedVersions`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsautoscaling`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listUsageRecords`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``isrecursive`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``oscategoryid`` | -| | - ``oscategoryname`` | -| | - ``osdisplayname`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``recoverVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``enableUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listZonesMetrics`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``suspendProject`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``migrateNetwork`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listUnmanagedInstances`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``hostname`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``registerTemplate`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``deployasis`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createZone`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listDomainChildren`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``domaindetails`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``importUnmanagedInstance`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listF5LoadBalancerNetworks`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createVolume`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``supportsstoragesnapshot`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listVMSnapshot`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``virtualmachinename`` | -| | - ``zonename`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updatePod`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ipranges(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``attachIso`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``forced`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createVMSnapshot`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``virtualmachinename`` | -| | - ``zonename`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listSSHKeyPairs`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``id`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listAccounts`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``showicon`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``removeNicFromVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``activateProject`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``account`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``enableAccount`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``created`` | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``startKubernetesCluster`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``autoscalingenabled`` | -| | - ``controlnodes`` | -| | - ``maxsize`` | -| | - ``minsize`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``deleteProject`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``cleanup`` (optional) | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``getUser`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createVpnCustomerGateway`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ikeversion`` (optional) | -| | - ``splitconnections`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ikeversion`` | -| | - ``splitconnections`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``createManagementNetworkIpRange`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``ipranges(*)`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``removeAnnotation`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``adminsonly`` | -| | - ``entityname`` | -| | - ``username`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``addBaremetalHost`` | **Request:** | -| | | -| | *Changed Parameters:* | -| | | -| | - ``password`` was 'required' and is now 'optional' | -| | - ``username`` was 'required' and is now 'optional' | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``destroyVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``listServiceOfferings`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``dynamicscalingenabled`` | -| | - ``storagetags`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``tags`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``assignVirtualMachineToBackupOffering`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``displaytext`` | -| | - ``success`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``id`` | -| | - ``account`` | -| | - ``accountid`` | -| | - ``backupofferingid`` | -| | - ``backupofferingname`` | -| | - ``created`` | -| | - ``domain`` | -| | - ``domainid`` | -| | - ``externalid`` | -| | - ``size`` | -| | - ``status`` | -| | - ``type`` | -| | - ``virtualmachineid`` | -| | - ``virtualmachinename`` | -| | - ``virtualsize`` | -| | - ``volumes`` | -| | - ``zone`` | -| | - ``zoneid`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``startVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``stopVirtualMachine`` | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``icon`` | -| | - ``lastupdated`` | -| | - ``pooltype`` | -| | - ``readonlydetails`` | -| | - ``receivedbytes`` | -| | - ``sentbytes`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``readonlyuidetails`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ -| ``updateServiceOffering`` | **Request:** | -| | | -| | *New Parameters:* | -| | | -| | - ``hosttags`` (optional) | -| | - ``storagetags`` (optional) | -| | | -| | **Response:** | -| | | -| | *New Parameters:* | -| | | -| | - ``dynamicscalingenabled`` | -| | - ``storagetags`` | -| | | -| | *Removed Parameters:* | -| | | -| | - ``tags`` | -| | | -+---------------------------------------------+--------------------------------------------------------------------------------+ - diff --git a/source/releasenotes/changes.rst b/source/releasenotes/changes.rst index f2ada48a6f..53c4232206 100644 --- a/source/releasenotes/changes.rst +++ b/source/releasenotes/changes.rst @@ -13,1109 +13,3236 @@ specific language governing permissions and limitations under the License. +Changes in |release| since 4.21.0.0 +=================================== -Changes in |release| since 4.15 -=============================== +Apache CloudStack uses GitHub https://github.com/apache/cloudstack/milestone/37?closed=1 +to track its issues -Apache CloudStack uses GitHub https://github.com/apache/cloudstack/milestone/16?closed=1 + +.. cssclass:: table-striped table-bordered table-hover + + ++-------------------------+---------------+------------------------------------------------------------+ +| Version | Github | Description | ++=========================+===============+============================================================+ +| 4.22.0.0 | `#11944`_ | NAS BnR: Fix error in Restore and attach volume | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11926`_ | [PowerFlex] Fix the config 'powerflex.connect.on.demand' | +| | | description | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11902`_ | Fix CKS cluster creation not honoring the CKS ISO arch | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11909`_ | UI: Minor fix for extra params display for VMware to KVM | +| | | migration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11908`_ | [VMware to KVM migration] Check source VM against the | +| | | selected offering | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11907`_ | Fix VMScheduler unit test for daylight saving time | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11651`_ | pre-commit add `chmod 644` manual hook for Markdown | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11870`_ | pre-commit auto add license headers for all Markdown files | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11065`_ | pre-commit: add oxipng a lossless PNG compression | +| | | optimizer | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11901`_ | Fix upgrade router template operation failure displayed on | +| | | the UI | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11900`_ | Avoid html escaping while saving vmsettings in | +| | | backup_details | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11892`_ | Fix: NPE thrown on VMware to KVM migration tasks listing | +| | | for removed VMs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11896`_ | UI: Fix duplicate memory values on InfoCard view | +| | | conditions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11887`_ | Fix OOB test failures in ci.yml github actions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11873`_ | Update CI workflow to use Ubuntu 24.04 and comply to PEP | +| | | 625 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11863`_ | Add erikbocks as a collaborator | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11856`_ | server: return extension path only to root admins | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11841`_ | Fixes for Import VM Tasks listing | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11318`_ | cloudutils: fix warning, error during kvm agent | +| | | installation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10223`_ | Allow counters to be created with same name, provider and | +| | | source as a deleted one | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11823`_ | systemvm: fix duplicated "en_US.UTF-8 UTF-8" in | +| | | /etc/locale.gen | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11419`_ | Add support for CSI driver in CKS | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11624`_ | Routed: fix create network exception when auto-allocation | +| | | is disabled | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11754`_ | NAS BnR: Create Instance from Backup issues | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11822`_ | agent: increase timeout for host arch retrieval | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11836`_ | Fix volume copy from primary to primary in simulator | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11832`_ | update the developers guide link on the API page during | +| | | generation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11786`_ | Support xz format for template registration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11767`_ | server: consistent behaviour for list apis with project=-1 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10423`_ | Add logs for host removal | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11766`_ | ui: Allow edit source CIDR on load balancer rule | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11413`_ | UI: Prevent exceptions when network service provider | +| | | that's disabled is viewed | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11548`_ | api,server,ui: allow cleaning up external details for host | +| | | and serviceoffering | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11688`_ | Standardize Markdown headings; enforce MD003 with | +| | | markdownlint | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11667`_ | pre-commit: enforce mixed-line-ending for all files | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11664`_ | Update GitHub Actions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11665`_ | Remove misspelled file not found from rat excludes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#9561`_ | Allow uploading of ISO for creating kubernetes supported | +| | | versions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11781`_ | PR #11778 with changes for main branch | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11465`_ | UI: Add validator for CIDR being passed | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11662`_ | pre-commit: add hooks `check-illegal-windows-names` and | +| | | `file-content… | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10135`_ | Removal of UI blockage to access the | +| | | `changeOfferingForVolume` API | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11446`_ | server: enable KVM volume and VM snapshot by default | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11470`_ | api/server: list networks by name | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10212`_ | Enforce distinct hostnames network | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11680`_ | Markdown: add documentation on pre-commit usage | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11811`_ | importvm: fix IP address allocation on Shared networks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11594`_ | VMware to KVM Migrations improvements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11613`_ | Added Extension for MaaS integration in CloudStack | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11738`_ | UI: Move Backup Repository to Infrastructure (from | +| | | Configuration) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11815`_ | ui: fix add host form state on submit | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11812`_ | UI: Fix for cluster addition in VMware | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11587`_ | API: Add support to list all snapshot policies & backup | +| | | schedules | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11625`_ | Migrate volume improvements, to bypass secondary storage | +| | | when copy volume between pools is allowed directly | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11782`_ | Delete template from storage pool instantly if no volume | +| | | is using it | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11589`_ | server: consistent domainpath in api responses | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11793`_ | update jetty | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11773`_ | storage: change storage pool to Up state when cancel | +| | | storage migration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11801`_ | Sanitize the rbd file cmd parameter logs during qemu-img | +| | | convert (through Script) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10282`_ | Add `Hypervisor default` as cache mode for disk offerings | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11760`_ | UI: Fix primary storage for datastore cluster and retain | +| | | traffic labels during zone deployment | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11488`_ | refactor: remove use of term entry-point from extensions | +| | | code base | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10533`_ | Deal with crosssite api call after login. | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11778`_ | systemvmtemplate: Bump Debian version to 12.12.0 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10740`_ | Storage pool response improvements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11654`_ | Add support for providing userdata to system VMs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11722`_ | Fix to not enable the disabled local storage(s) on host | +| | | connection | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11541`_ | Make kvm domain persistent when unmanaged from CS | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11228`_ | server: add user.password.reset.smtp.useStartTLS and | +| | | enabledSecurityProtocols for password reset | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11684`_ | NAS backup provider: Support restore from backup to | +| | | volumes on Ceph storage pool(s), and take backup for | +| | | stopped instances with volumes on Ceph storage pool(s) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11787`_ | linstor: use sparse/discard qemu-img convert on thin | +| | | devices | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10641`_ | VMware: match nic mac for ip address fetch | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10983`_ | Fixed and enhanced vlan field validation in the UI | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11735`_ | CKS: fix CKS creation on an existing Shared or Routed | +| | | network | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11771`_ | ui: fix overflow for value in DetailInput | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11522`_ | Fix removeUsage for backups | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11751`_ | Consider Instance in Starting state as well for allocation | +| | | algorithm | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11462`_ | Add UUID field for LDAP configuration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11726`_ | Shared Filesystem support on Config Drive Networks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11732`_ | Extensions: use home directory of cloud user instead of | +| | | /var/lib/cloudstack/management/ | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11639`_ | CKS: generate a random UUID as password of CKS user in | +| | | project | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11715`_ | Fix detection of Mi3xx GPUs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11719`_ | UI support for extraconfig in deploy and update instance | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11753`_ | Fix importing unmanaged instances due to incorrect | +| | | internal name | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11741`_ | noVNC: make show dot configurable | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11720`_ | CKS: fix control plane endpoint IP | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11601`_ | extension/proxmox: add console access for instances | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10962`_ | systemvm: fix failed to get script version when patch | +| | | system vm or router | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11198`_ | server: set download volume format to qcow2 for KVM | +| | | volumes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11546`_ | Add support EL10 & support java 21 for EL10 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11560`_ | Create Instance from backup on another Zone (DRaaS use | +| | | case) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11702`_ | ui: do not show admin only options to users while | +| | | registering template | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11687`_ | KVM: fix delete vm snapshot if it does not exist with a | +| | | Stopped vm | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11696`_ | LDAP: honour nested groups for MSAD | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11686`_ | Fix vpclimit count for listAcccount API response | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11530`_ | server: set VirtualMachineTO arch from template if present | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11640`_ | honor templateId passed in importVM API | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11666`_ | Mount the disabled storage pools by default | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11612`_ | ui: allow provisioning backups during instance deploy | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11659`_ | Fix VM import DB sequence issue on import failure | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#8452`_ | Cleanup allocated snapshots / vm snapshots, and update | +| | | pending ones to Error on MS start | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11259`_ | ui: fix build on latest Ubuntu and macOS | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11506`_ | Update gson date format for serializing/deserializing Date | +| | | in MS stats | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11682`_ | api,server: support templatetype when upload template from | +| | | local | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11681`_ | VR: consider NICs for remote access VPN when apply dhcp | +| | | entry | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10710`_ | [router] make a distinction between fatal errors, warnings | +| | | and unknown as healthcheck result | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11652`_ | Fix scaleKubernetesCluster API | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11017`_ | Add yamllint pre-commit hook for YAML file standardization | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11464`_ | Add cleanup for tiers dropdown on assignVirtualMachine API | +| | | form | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11676`_ | chore(markdown): use https on links | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11670`_ | use /prod/stat to get uptime instead of the uptime command | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11618`_ | Netris: Fix inactive VPCs deletion | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11663`_ | PULL_REQUEST_TEMPLATE standardize case of types of changes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11284`_ | java: fix one typo in many files | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11285`_ | Fix spelling in Java and Python files; update the ignored | +| | | words list `codespell.txt` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10150`_ | pre-commit add hook `check-shebang-scripts-are-executable` | +| | | for Shell | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11289`_ | misc: pre-commit auto remove unneeded trailing whitespace | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11415`_ | Move console proxy related global settings to Zone level | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11568`_ | Allow updating of Load Balancer source CIDR list | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#9793`_ | pre-commit: clean up Python flake8 excludes with black | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11300`_ | Add CodeQL Analysis for GitHub Actions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11617`_ | Filter netris vNets only by VPC ID as filter by site isn't | +| | | working as expected on Netris end | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11569`_ | [KVM] Allow passing the OS type machine for KVM XML | +| | | domains through VM setting | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11410`_ | Add LB service to Custom Netris VPC/Network offerings | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11632`_ | Fix for No VMs start after Renew Host Security Keys due to | +| | | wrong qemu group reading | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11602`_ | [UI] Fix group disable action for compute and disk | +| | | offering | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11590`_ | ui: fix tab name in query params | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11389`_ | Fix NPE during VM IP fetch for shared networks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11576`_ | ui: searchview change should only remove related query | +| | | params | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11406`_ | Add all workflow buttons to README | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11558`_ | server: check limit on correct store during snapshot | +| | | allocation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11554`_ | ScaleIO/PowerFlex smoke tests improvements, and some fixes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11614`_ | fix qemu-img path in cloudstack sudoers | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11468`_ | Improvement: SSL offloading with Virtual Router | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10735`_ | ssvm: use mgmt network if no storage network | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11598`_ | Fix transition exception when scaling Stopped k8s clusters | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11610`_ | Fix NPE in case host UEFI detail is not set on agent | +| | | connection | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11507`_ | Import KVM VM: Autodetect vlan id from bridge name | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10970`_ | IPv6 firewall: accept packets from related and established | +| | | connections | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#9305`_ | server: allow migration of vm with snapshots for vmware | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10869`_ | Change log level of AgentHandler#processRequest() | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11556`_ | server: allow adding non-overlapping ipv6 ranges in same | +| | | vlan | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11528`_ | CKS: Validate network offering from network if provided | +| | | rather than global setting | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11575`_ | ui: donot remove account, domain from query on public ip | +| | | filter change | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11314`_ | server: prevent vm schedule update failure for time when | +| | | not changed | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11218`_ | server,kvm: detect boot options for vm import | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10734`_ | 2fa: log error on totp mismatch | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11487`_ | Delete session after key expiration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11361`_ | Make logout function more robust to prevent session issues | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11553`_ | [UI] Fix display of disk size and IOPS fields in the scale | +| | | VM form | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11557`_ | kvm: add ssvm storage nic null uri check during plug | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11543`_ | systemvm template: update URLs of debian ISOs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11536`_ | ui: show multiple domains as links in list view | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11329`_ | server: remove extra chars when template status is error | +| | | string | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11485`_ | Don't show backup in list_capacity for dummy plugin or if | +| | | backup_framework is disabled | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10865`_ | ui: do not filter edge zones while registering | +| | | directdownload iso | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11134`_ | Update md5sum to sha512sum | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11489`_ | ui: fix extension path with name having special characters | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11230`_ | Added events for snapshots, vmsnapshots, internalLB | +| | | operations | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11540`_ | make server threads configurable with server.properties | +| | | file | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11542`_ | test: fix test_04_rvpc_network_garbage_collector_nics | +| | | failure | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11550`_ | [UI] Use update offering APIs to disable compute and disk | +| | | offerings | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11030`_ | .github: Update to JDK 17 in ci.yml and build.yml | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11136`_ | utils: add UuidUtils.nameUUIDFromBytes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11135`_ | packaging: add pre-check.sh | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11379`_ | Remove Domain/IP from Password Reset Link to custom Global | +| | | Setting | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11469`_ | schema: Add upgrade path from 4.21.0.0 to 4.22.0.0 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11537`_ | api: use single quote instead of double quote in | +| | | StatsResponse | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11532`_ | kvm: fix vm deployment with direct-download iso | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10152`_ | Add response object required by go SDK for parsing | +| | | response | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11243`_ | SG: Apply rules for both ipv4/ipv6 of VMs with associated | +| | | account/SG | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10545`_ | UI: Hide User Card from config.userCard.enabled option | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#10723`_ | Add logs to keystore-setup and fix password regex | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11518`_ | VPC VR: return UNKNOWN redundant state if no guest nics | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11466`_ | UI: Prevent restriction of changeOfferingForVolume API to | +| | | Admin role | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11504`_ | scripts: fix external provision to use correct power state | +| | | & hyperv powersync | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.22.0.0 | `#11516`_ | Fix for live migration of VM with config drive, on KVM | ++-------------------------+---------------+------------------------------------------------------------+ + +177 Issues listed + +.. _`#11944`: https://github.com/apache/cloudstack/pull/11944 +.. _`#11926`: https://github.com/apache/cloudstack/pull/11926 +.. _`#11902`: https://github.com/apache/cloudstack/pull/11902 +.. _`#11909`: https://github.com/apache/cloudstack/pull/11909 +.. _`#11908`: https://github.com/apache/cloudstack/pull/11908 +.. _`#11907`: https://github.com/apache/cloudstack/pull/11907 +.. _`#11651`: https://github.com/apache/cloudstack/pull/11651 +.. _`#11870`: https://github.com/apache/cloudstack/pull/11870 +.. _`#11065`: https://github.com/apache/cloudstack/pull/11065 +.. _`#11901`: https://github.com/apache/cloudstack/pull/11901 +.. _`#11900`: https://github.com/apache/cloudstack/pull/11900 +.. _`#11892`: https://github.com/apache/cloudstack/pull/11892 +.. _`#11896`: https://github.com/apache/cloudstack/pull/11896 +.. _`#11887`: https://github.com/apache/cloudstack/pull/11887 +.. _`#11873`: https://github.com/apache/cloudstack/pull/11873 +.. _`#11863`: https://github.com/apache/cloudstack/pull/11863 +.. _`#11856`: https://github.com/apache/cloudstack/pull/11856 +.. _`#11841`: https://github.com/apache/cloudstack/pull/11841 +.. _`#11318`: https://github.com/apache/cloudstack/pull/11318 +.. _`#10223`: https://github.com/apache/cloudstack/pull/10223 +.. _`#11823`: https://github.com/apache/cloudstack/pull/11823 +.. _`#11419`: https://github.com/apache/cloudstack/pull/11419 +.. _`#11624`: https://github.com/apache/cloudstack/pull/11624 +.. _`#11754`: https://github.com/apache/cloudstack/pull/11754 +.. _`#11822`: https://github.com/apache/cloudstack/pull/11822 +.. _`#11836`: https://github.com/apache/cloudstack/pull/11836 +.. _`#11832`: https://github.com/apache/cloudstack/pull/11832 +.. _`#11786`: https://github.com/apache/cloudstack/pull/11786 +.. _`#11767`: https://github.com/apache/cloudstack/pull/11767 +.. _`#10423`: https://github.com/apache/cloudstack/pull/10423 +.. _`#11766`: https://github.com/apache/cloudstack/pull/11766 +.. _`#11413`: https://github.com/apache/cloudstack/pull/11413 +.. _`#11548`: https://github.com/apache/cloudstack/pull/11548 +.. _`#11688`: https://github.com/apache/cloudstack/pull/11688 +.. _`#11667`: https://github.com/apache/cloudstack/pull/11667 +.. _`#11664`: https://github.com/apache/cloudstack/pull/11664 +.. _`#11665`: https://github.com/apache/cloudstack/pull/11665 +.. _`#9561`: https://github.com/apache/cloudstack/pull/9561 +.. _`#11781`: https://github.com/apache/cloudstack/pull/11781 +.. _`#11465`: https://github.com/apache/cloudstack/pull/11465 +.. _`#11662`: https://github.com/apache/cloudstack/pull/11662 +.. _`#10135`: https://github.com/apache/cloudstack/pull/10135 +.. _`#11446`: https://github.com/apache/cloudstack/pull/11446 +.. _`#11470`: https://github.com/apache/cloudstack/pull/11470 +.. _`#10212`: https://github.com/apache/cloudstack/pull/10212 +.. _`#11680`: https://github.com/apache/cloudstack/pull/11680 +.. _`#11811`: https://github.com/apache/cloudstack/pull/11811 +.. _`#11594`: https://github.com/apache/cloudstack/pull/11594 +.. _`#11613`: https://github.com/apache/cloudstack/pull/11613 +.. _`#11738`: https://github.com/apache/cloudstack/pull/11738 +.. _`#11815`: https://github.com/apache/cloudstack/pull/11815 +.. _`#11812`: https://github.com/apache/cloudstack/pull/11812 +.. _`#11587`: https://github.com/apache/cloudstack/pull/11587 +.. _`#11625`: https://github.com/apache/cloudstack/pull/11625 +.. _`#11782`: https://github.com/apache/cloudstack/pull/11782 +.. _`#11589`: https://github.com/apache/cloudstack/pull/11589 +.. _`#11793`: https://github.com/apache/cloudstack/pull/11793 +.. _`#11773`: https://github.com/apache/cloudstack/pull/11773 +.. _`#11801`: https://github.com/apache/cloudstack/pull/11801 +.. _`#10282`: https://github.com/apache/cloudstack/pull/10282 +.. _`#11760`: https://github.com/apache/cloudstack/pull/11760 +.. _`#11488`: https://github.com/apache/cloudstack/pull/11488 +.. _`#10533`: https://github.com/apache/cloudstack/pull/10533 +.. _`#11778`: https://github.com/apache/cloudstack/pull/11778 +.. _`#10740`: https://github.com/apache/cloudstack/pull/10740 +.. _`#11654`: https://github.com/apache/cloudstack/pull/11654 +.. _`#11722`: https://github.com/apache/cloudstack/pull/11722 +.. _`#11541`: https://github.com/apache/cloudstack/pull/11541 +.. _`#11228`: https://github.com/apache/cloudstack/pull/11228 +.. _`#11684`: https://github.com/apache/cloudstack/pull/11684 +.. _`#11787`: https://github.com/apache/cloudstack/pull/11787 +.. _`#10641`: https://github.com/apache/cloudstack/pull/10641 +.. _`#10983`: https://github.com/apache/cloudstack/pull/10983 +.. _`#11735`: https://github.com/apache/cloudstack/pull/11735 +.. _`#11771`: https://github.com/apache/cloudstack/pull/11771 +.. _`#11522`: https://github.com/apache/cloudstack/pull/11522 +.. _`#11751`: https://github.com/apache/cloudstack/pull/11751 +.. _`#11462`: https://github.com/apache/cloudstack/pull/11462 +.. _`#11726`: https://github.com/apache/cloudstack/pull/11726 +.. _`#11732`: https://github.com/apache/cloudstack/pull/11732 +.. _`#11639`: https://github.com/apache/cloudstack/pull/11639 +.. _`#11715`: https://github.com/apache/cloudstack/pull/11715 +.. _`#11719`: https://github.com/apache/cloudstack/pull/11719 +.. _`#11753`: https://github.com/apache/cloudstack/pull/11753 +.. _`#11741`: https://github.com/apache/cloudstack/pull/11741 +.. _`#11720`: https://github.com/apache/cloudstack/pull/11720 +.. _`#11601`: https://github.com/apache/cloudstack/pull/11601 +.. _`#10962`: https://github.com/apache/cloudstack/pull/10962 +.. _`#11198`: https://github.com/apache/cloudstack/pull/11198 +.. _`#11546`: https://github.com/apache/cloudstack/pull/11546 +.. _`#11560`: https://github.com/apache/cloudstack/pull/11560 +.. _`#11702`: https://github.com/apache/cloudstack/pull/11702 +.. _`#11687`: https://github.com/apache/cloudstack/pull/11687 +.. _`#11696`: https://github.com/apache/cloudstack/pull/11696 +.. _`#11686`: https://github.com/apache/cloudstack/pull/11686 +.. _`#11530`: https://github.com/apache/cloudstack/pull/11530 +.. _`#11640`: https://github.com/apache/cloudstack/pull/11640 +.. _`#11666`: https://github.com/apache/cloudstack/pull/11666 +.. _`#11612`: https://github.com/apache/cloudstack/pull/11612 +.. _`#11659`: https://github.com/apache/cloudstack/pull/11659 +.. _`#8452`: https://github.com/apache/cloudstack/pull/8452 +.. _`#11259`: https://github.com/apache/cloudstack/pull/11259 +.. _`#11506`: https://github.com/apache/cloudstack/pull/11506 +.. _`#11682`: https://github.com/apache/cloudstack/pull/11682 +.. _`#11681`: https://github.com/apache/cloudstack/pull/11681 +.. _`#10710`: https://github.com/apache/cloudstack/pull/10710 +.. _`#11652`: https://github.com/apache/cloudstack/pull/11652 +.. _`#11017`: https://github.com/apache/cloudstack/pull/11017 +.. _`#11464`: https://github.com/apache/cloudstack/pull/11464 +.. _`#11676`: https://github.com/apache/cloudstack/pull/11676 +.. _`#11670`: https://github.com/apache/cloudstack/pull/11670 +.. _`#11618`: https://github.com/apache/cloudstack/pull/11618 +.. _`#11663`: https://github.com/apache/cloudstack/pull/11663 +.. _`#11284`: https://github.com/apache/cloudstack/pull/11284 +.. _`#11285`: https://github.com/apache/cloudstack/pull/11285 +.. _`#10150`: https://github.com/apache/cloudstack/pull/10150 +.. _`#11289`: https://github.com/apache/cloudstack/pull/11289 +.. _`#11415`: https://github.com/apache/cloudstack/pull/11415 +.. _`#11568`: https://github.com/apache/cloudstack/pull/11568 +.. _`#9793`: https://github.com/apache/cloudstack/pull/9793 +.. _`#11300`: https://github.com/apache/cloudstack/pull/11300 +.. _`#11617`: https://github.com/apache/cloudstack/pull/11617 +.. _`#11569`: https://github.com/apache/cloudstack/pull/11569 +.. _`#11410`: https://github.com/apache/cloudstack/pull/11410 +.. _`#11632`: https://github.com/apache/cloudstack/pull/11632 +.. _`#11602`: https://github.com/apache/cloudstack/pull/11602 +.. _`#11590`: https://github.com/apache/cloudstack/pull/11590 +.. _`#11389`: https://github.com/apache/cloudstack/pull/11389 +.. _`#11576`: https://github.com/apache/cloudstack/pull/11576 +.. _`#11406`: https://github.com/apache/cloudstack/pull/11406 +.. _`#11558`: https://github.com/apache/cloudstack/pull/11558 +.. _`#11554`: https://github.com/apache/cloudstack/pull/11554 +.. _`#11614`: https://github.com/apache/cloudstack/pull/11614 +.. _`#11468`: https://github.com/apache/cloudstack/pull/11468 +.. _`#10735`: https://github.com/apache/cloudstack/pull/10735 +.. _`#11598`: https://github.com/apache/cloudstack/pull/11598 +.. _`#11610`: https://github.com/apache/cloudstack/pull/11610 +.. _`#11507`: https://github.com/apache/cloudstack/pull/11507 +.. _`#10970`: https://github.com/apache/cloudstack/pull/10970 +.. _`#9305`: https://github.com/apache/cloudstack/pull/9305 +.. _`#10869`: https://github.com/apache/cloudstack/pull/10869 +.. _`#11556`: https://github.com/apache/cloudstack/pull/11556 +.. _`#11528`: https://github.com/apache/cloudstack/pull/11528 +.. _`#11575`: https://github.com/apache/cloudstack/pull/11575 +.. _`#11314`: https://github.com/apache/cloudstack/pull/11314 +.. _`#11218`: https://github.com/apache/cloudstack/pull/11218 +.. _`#10734`: https://github.com/apache/cloudstack/pull/10734 +.. _`#11487`: https://github.com/apache/cloudstack/pull/11487 +.. _`#11361`: https://github.com/apache/cloudstack/pull/11361 +.. _`#11553`: https://github.com/apache/cloudstack/pull/11553 +.. _`#11557`: https://github.com/apache/cloudstack/pull/11557 +.. _`#11543`: https://github.com/apache/cloudstack/pull/11543 +.. _`#11536`: https://github.com/apache/cloudstack/pull/11536 +.. _`#11329`: https://github.com/apache/cloudstack/pull/11329 +.. _`#11485`: https://github.com/apache/cloudstack/pull/11485 +.. _`#10865`: https://github.com/apache/cloudstack/pull/10865 +.. _`#11134`: https://github.com/apache/cloudstack/pull/11134 +.. _`#11489`: https://github.com/apache/cloudstack/pull/11489 +.. _`#11230`: https://github.com/apache/cloudstack/pull/11230 +.. _`#11540`: https://github.com/apache/cloudstack/pull/11540 +.. _`#11542`: https://github.com/apache/cloudstack/pull/11542 +.. _`#11550`: https://github.com/apache/cloudstack/pull/11550 +.. _`#11030`: https://github.com/apache/cloudstack/pull/11030 +.. _`#11136`: https://github.com/apache/cloudstack/pull/11136 +.. _`#11135`: https://github.com/apache/cloudstack/pull/11135 +.. _`#11379`: https://github.com/apache/cloudstack/pull/11379 +.. _`#11469`: https://github.com/apache/cloudstack/pull/11469 +.. _`#11537`: https://github.com/apache/cloudstack/pull/11537 +.. _`#11532`: https://github.com/apache/cloudstack/pull/11532 +.. _`#10152`: https://github.com/apache/cloudstack/pull/10152 +.. _`#11243`: https://github.com/apache/cloudstack/pull/11243 +.. _`#10545`: https://github.com/apache/cloudstack/pull/10545 +.. _`#10723`: https://github.com/apache/cloudstack/pull/10723 +.. _`#11518`: https://github.com/apache/cloudstack/pull/11518 +.. _`#11466`: https://github.com/apache/cloudstack/pull/11466 +.. _`#11504`: https://github.com/apache/cloudstack/pull/11504 +.. _`#11516`: https://github.com/apache/cloudstack/pull/11516 + +Changes in |release| since 4.20.1.0 +=================================== + +Apache CloudStack uses GitHub https://github.com/apache/cloudstack/milestone/35?closed=1 +to track its issues + +.. cssclass:: table-striped table-bordered table-hover + + ++-------------------------+---------------+------------------------------------------------------------+ +| Version | Github | Description | ++=========================+===============+============================================================+ +| 4.21.0.0 | `#11490`_ | Fix of create a template from a StorPool snapshot on | +| | | another zone | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11457`_ | Fix deployment of CKS clusters in Basic zone | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11463`_ | Remove non-existent network service provider from UI | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11455`_ | Update error message when no snapshot strategy is found | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11458`_ | Fix for PowerFlex MDM configuration on host while | +| | | preparing the SDC connection | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11452`_ | Fix for create template from snapshot (for snapshots on | +| | | primary storage and storage doesn't support create | +| | | snapshot to template directly) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10964`_ | [KVM] CPU Features for System VMs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11448`_ | Fix snapshot physical size listing | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11450`_ | Proxmox: fix restore snapshot with memory | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11397`_ | linstor: fix getVolumeStats if multiple Linstor primary | +| | | storages are used | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11133`_ | server: fix conserve_mode of | +| | | DefaultIsolatedNetworkOfferingForVpcNetworks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11435`_ | Exclude External hypervisor type during upgrade for System | +| | | VM template checks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11401`_ | UI: fix addHost error in zone creation wizard | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11432`_ | Add support for nvidia vGPU support with vendor specific | +| | | framework | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10485`_ | Fix ConfigurationVO load exception after schema change | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11393`_ | ui: make vpc cidr required when not showing cidrsize | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10645`_ | Network rate must be multiplied by 125 not 128 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11418`_ | noVNC: Show a dot cursor when the cursor is not visible | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11427`_ | UI: Fix duplicate edit zone button on Basic zones | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11417`_ | Fix edit of compute offering in UI | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11062`_ | api: fix scale or upgrade systemvm | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11404`_ | [UI] Fix zone creation wizard stuck on configuring public | +| | | traffic | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11351`_ | Fix of deployment VM from a copied snapshot in another | +| | | zone | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11386`_ | get forward header for proxies and apply it in Jetty | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11392`_ | cleanup: remove com.cloud.user.MockAccountManagerImpl | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11242`_ | server: fix vm deployment without networkid in a zone with | +| | | shared networks | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11376`_ | Agent connection improvements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10860`_ | Fix infrastructure leak on exception while | +| | | attaching/detaching volumes in VMware | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11388`_ | Fix create statement for safer upgrades | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11384`_ | Remove volume size check in restoreBackupToVM | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11373`_ | juniper-contrail: publish events only for the module | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9733`_ | custom AccessLogger | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9478`_ | Support of snapshot copy to primary storage in different | +| | | zones. | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11366`_ | fix storage pool capacity threshold flag | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11197`_ | Handle project delete in details view | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11315`_ | ui: pass validated storagepolicy for swift store | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11380`_ | plugin-swift: handle null cache store | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11298`_ | added online/offline copy method for Primera storage | +| | | adapter | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11181`_ | Improve volume backup restoration log | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11115`_ | ceph: fix SignatureDoesNotMatch by using correct secret | +| | | key when create bucket | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11372`_ | cloud.spec: provide option between tzdata-java and | +| | | timezone-java | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11377`_ | Netris: Fix Netris provider parameter name and response | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11016`_ | API to list console sessions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11374`_ | Fix failing simulator vgpu test | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11349`_ | ui: fix initial pagination for images in deploy forms | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11254`_ | agent: increase timeout for host arch retrieval | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11369`_ | ui: update project menu on projects change | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11370`_ | ui: fix api type in InfiniteScrollSelect | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11291`_ | Update System VM template Guest OS version | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11355`_ | api,server,ui: allow listing events by state | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11164`_ | UI support for deploy a VM from volume/snapshot | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11107`_ | Refactoring smoke tests | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11340`_ | Fix GPU discovery script to make it run with mdev for | +| | | SR-IOV enabled devices | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11313`_ | Show chain size in snapshot response for incremental | +| | | snapshots | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11353`_ | UI: Fix cpu & memory details on list view for unmanaged | +| | | k8s clusters (CAPC) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10946`_ | Find system VM templates for CKS clusters and SharedFS | +| | | honouring the preferred architecture | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11177`_ | Allow full clone volumes with thin provisioning | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11070`_ | fix fsvm-init.yml to detect virtio-scsi in kvm | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10140`_ | Create new Instance from VM backup | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10902`_ | Selected update traffic type based on chosen traffic type | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11337`_ | ui: fix delete traffic type | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11354`_ | [UI] Use GET request method for list API calls | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11352`_ | API: Set Object name when expunging VM | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11343`_ | Support to list templates in ready state (new API | +| | | parameter 'isready', similar to list ISOs) | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11330`_ | Shutdown MS maintenance jobs when finished | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11223`_ | Refactoring retention of backup schedules | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11142`_ | UI: Display NSX Provider only when NSX is the selected | +| | | Isolation method | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11316`_ | Fix listCapacity sort by usage | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11342`_ | kvm: fix regression | +| | | 5a52ca78ae5e165211c618525613c3d62cfd1b28 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11317`_ | ui: make events tab selected columns persistent using | +| | | cache | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11245`_ | kvm, ui: fix interface when using vlan subnet for storage | +| | | traffic type | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11306`_ | ui: fix advance setting behaviour in autoscale form | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11332`_ | Fix build and ui build errors in main | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11119`_ | Upgrade noVNC from 1.4.0 to 1.6.0 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11310`_ | server: fix IllegalMonitorStateException on cluster | +| | | managedstate change | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11328`_ | ui: fix volume size not showing | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11068`_ | [Multi-Arch] Select Template Arch when creating template | +| | | from volume | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11249`_ | Update CIDR/Gateway of the Shared Networks from Guest IP | +| | | ranges | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11143`_ | Feature: Add support for GPU with KVM hosts | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11311`_ | README: add `Contributors Avatars` and `Star History` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11244`_ | Prevent infinite autoscaling | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11303`_ | api,server,extensions: allow updating extension resource | +| | | map details | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11200`_ | Fix local storage pool disconnect issue | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11307`_ | ui: fix NAN% used memory for vm | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11302`_ | server: fix NaN metrics for external resources | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11309`_ | [UI] Fix for local storage enable/disable toggle in edit | +| | | zone | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11042`_ | Add unit tests for getConfigResources in | +| | | ModuleDefinitionSet and improve context readability | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11237`_ | Prevent multi-select dropdown menu from floating on | +| | | scrolling through the form | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11239`_ | [DB] Add force recreate parameter to | +| | | cloudstack-setup-databases script | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9752`_ | Extensions Framework & Orchestrate Anything | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11232`_ | ui: fix compute offering edit | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11195`_ | [UI] Add dedicated account field dropdown on zone creation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11292`_ | schema,framework/db,server: fix user_vm_details usage | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10986`_ | [CKS] Create Kubernetes ISO support for ARCH optional | +| | | parameter | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11220`_ | Mark LDAP user query timeout as incorrect login instead of | +| | | disabling user immediately | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11210`_ | Allow custom NTP servers for CPVM | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11053`_ | linstor: Use template's uuid if pool's downloadPath is | +| | | null as resour… | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10458`_ | Netris Network Plugin Integration with CloudStack | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11264`_ | Validate qcow2 file during import operation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11256`_ | Config 'vm.network.nic.max.secondary.ipaddresses' - Update | +| | | default value (and value if not set) to 10 as per the | +| | | config description and default value in parseInt of the | +| | | config | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11276`_ | Fix pre-commit warnings for deprecated stage names | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10975`_ | [Vmware to KVM Migration] Preserve boot type and boot mode | +| | | of instances to be migrated | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10856`_ | polish: Fix some inconsistencies in object names and | +| | | messages | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10935`_ | UI: Add option to Login to a specific Project view via | +| | | setting on config.json | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11221`_ | console: optimise buffer sizes for faster console | +| | | performance | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11207`_ | [UI] Deploy VM: Restore preselection of the first | +| | | available template | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10736`_ | schema, refactor: rename cloud.user_vm_details to | +| | | cloud.vm_instance_details | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11102`_ | UI: Fix missing labels | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10966`_ | misc: fix typo `sercurity` -> `security` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11075`_ | UI: Fix OS Type displayed for a VM | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11087`_ | list only own zones for resource admin | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11086`_ | Fix for dynamic scaling toggle for instance | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11064`_ | pre-commit: add gitleaks to detect hardcoded secrets | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11067`_ | Fix HTML license; standardize HTML code | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11066`_ | pre-commit: upgrade markdownlint to the latest version | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11265`_ | add since parameter to BackupScheduleResponse | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11258`_ | Fix restore from NAS backup when datadisk is older than | +| | | the root disk. | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11204`_ | NAS backup provider: Support backup and restore with | +| | | Shared mount point primary storage. | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11093`_ | Object storage browser: Get Content-Type from the file | +| | | extension during upload | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11196`_ | OVM deprecation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11261`_ | UI: Fix ISO Hypervisor selection | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11222`_ | Fix deletion of backup schedules | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10857`_ | Add special Icon to Shared FileSystem Instances | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11211`_ | Fix to create instances with smaller templates (< 1 GB) on | +| | | PowerFlex/ScaleIO storage | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11215`_ | Guard OS type update for iso/template with existing vms | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11180`_ | Fix KVM incremental snapshot removal when using multiple | +| | | secondary storages | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11214`_ | Add format and physicalsize in listIsoOs api response | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10879`_ | Handle exception for decoder while uploading ISO from | +| | | local | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11138`_ | Fix update resource count failure for domains | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11231`_ | Update .asf.yaml: remove new committer Bernardo | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11054`_ | npe guard for get host info on vmware | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10917`_ | kvm: consider Debian same as Ubuntu | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11101`_ | UI: Fix traffic Label on Zone creation wizard for VMware | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11179`_ | List templates and ISOs by domain | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10947`_ | Allow populating generic templates during Zone Deployment | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11099`_ | PowerFlex/ScaleIO - Wait after SDC service | +| | | start/restart/stop, and retry to fetch SDC id/guid | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10632`_ | File-based disk-only VM snapshot with KVM as hypervisor | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11097`_ | Usage parsers refactoring | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11047`_ | PowerFlex/ScaleIO - MDM and host SDC connection | +| | | enhancements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11063`_ | [CKS] Simplify logic for scaling CKS cluster service | +| | | offerings | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11191`_ | UI fix api in project view | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11128`_ | systemvm: build 4.20.2 template with 'depmod -a' | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10997`_ | CPU to Memory weight based algorithm to order cluster | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#8942`_ | GUI whitelabel runtime system | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10575`_ | Hide CloudStack version from XML response when | +| | | unauthenticated | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10848`_ | Remove unfinished usage job entries of the host on start | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10503`_ | KVM: Option to deploy a VM with existing volume/snapshot | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11109`_ | fix priority for volume copy operation | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11171`_ | schema: fix missing columns index | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10504`_ | Refactor: Replace sleep() with wait() | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10576`_ | Inefficient use of a for loop | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11170`_ | Improve error when a template to owned by non root-admin | +| | | is registered for all zones. | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11158`_ | .github: restrict codecov in UI build to apache/cloudstack | +| | | repo | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11168`_ | UI: Fix volumes `SearchView` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11091`_ | [Vmware to KVM Migration] Fix issue with vCenter | +| | | Standalone hosts for VM listing | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11113`_ | directdownload: fix keytool importcert | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10951`_ | Allow configuring Announcement banner by admin | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10899`_ | Support ApiServer to enforce POST requests for state | +| | | changing APIs and requests with timestamps | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10778`_ | Normalize naming of Kubernetes clusters | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10325`_ | Add API command remove management server | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11003`_ | [VMware to KVM Migration] Fix for converted instance NPE | +| | | issue when source VMware instance OVF is exported from | +| | | management server | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11116`_ | ui: fix handler for deploy button menu | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11095`_ | server: fix orphan db transaction issue | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11085`_ | Corrected quota type indexes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10995`_ | Management Server - Prepare for Maintenance and Cancel | +| | | Maintenance improvements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11106`_ | Do not rely on Memory engine in DB setup scripts | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11004`_ | Block volume shrink on Xen | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11069`_ | Support Direct Download on Ceph primary storage | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11060`_ | ui: fix missing changes from #10814 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11019`_ | [Vmware to KVM Migration] Display virt-v2v and ovftool | +| | | versions for supported hosts for migration | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11035`_ | [Vmware to KVM Migration] Improve the Force MS option text | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11057`_ | docs: Update INSTALL.md for frontend build instructions | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11055`_ | Add check for ldap truststore password | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9102`_ | CKS Enhancements | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11040`_ | Changes baseurl for downloading kubectl | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9277`_ | Add access modifiers to `VirtualMachineTO` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11025`_ | docs: revise INSTALL.md with updated Maven setup | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11013`_ | Remove test/selenium/ test/src-not-used/ | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10475`_ | Fix volume allocation logs | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10077`_ | enabled discard option | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9833`_ | StorPool: support for direct download | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10896`_ | Check Qcow2 version before using --bitmaps | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10987`_ | Fix data being replicated on VM's metadata file in VR | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#9969`_ | Add parameter to not create additional users on | +| | | `cloudstack-setup-databases` | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11011`_ | engine-schema: fix naming for AlmaLinux | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11012`_ | docs: fix outdated Maven subtitle in INSTALL.md | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11001`_ | engine-schema: fix duplicate statements in upgrade path | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#11010`_ | ui: fix build after forward merge | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10587`_ | StorPool added device ID tag to the StorPool volumes | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10663`_ | Accept case insensitive values in boolean settings | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10773`_ | ui,api,server: template categorization based on os | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10814`_ | ui: show deploy/create button on right info pane | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10949`_ | ui: missing changes from #10115 | ++-------------------------+---------------+------------------------------------------------------------+ +| 4.21.0.0 | `#10769`_ | Log previous and new value of configuration when | +| | | reset/update API is called | ++-------------------------+---------------+------------------------------------------------------------+ + +194 Issues listed + +.. _`#11490`: https://github.com/apache/cloudstack/pull/11490 +.. _`#11457`: https://github.com/apache/cloudstack/pull/11457 +.. _`#11463`: https://github.com/apache/cloudstack/pull/11463 +.. _`#11455`: https://github.com/apache/cloudstack/pull/11455 +.. _`#11458`: https://github.com/apache/cloudstack/pull/11458 +.. _`#11452`: https://github.com/apache/cloudstack/pull/11452 +.. _`#10964`: https://github.com/apache/cloudstack/pull/10964 +.. _`#11448`: https://github.com/apache/cloudstack/pull/11448 +.. _`#11450`: https://github.com/apache/cloudstack/pull/11450 +.. _`#11397`: https://github.com/apache/cloudstack/pull/11397 +.. _`#11133`: https://github.com/apache/cloudstack/pull/11133 +.. _`#11435`: https://github.com/apache/cloudstack/pull/11435 +.. _`#11401`: https://github.com/apache/cloudstack/pull/11401 +.. _`#11432`: https://github.com/apache/cloudstack/pull/11432 +.. _`#10485`: https://github.com/apache/cloudstack/pull/10485 +.. _`#11393`: https://github.com/apache/cloudstack/pull/11393 +.. _`#10645`: https://github.com/apache/cloudstack/pull/10645 +.. _`#11418`: https://github.com/apache/cloudstack/pull/11418 +.. _`#11427`: https://github.com/apache/cloudstack/pull/11427 +.. _`#11417`: https://github.com/apache/cloudstack/pull/11417 +.. _`#11062`: https://github.com/apache/cloudstack/pull/11062 +.. _`#11404`: https://github.com/apache/cloudstack/pull/11404 +.. _`#11351`: https://github.com/apache/cloudstack/pull/11351 +.. _`#11386`: https://github.com/apache/cloudstack/pull/11386 +.. _`#11392`: https://github.com/apache/cloudstack/pull/11392 +.. _`#11242`: https://github.com/apache/cloudstack/pull/11242 +.. _`#11376`: https://github.com/apache/cloudstack/pull/11376 +.. _`#10860`: https://github.com/apache/cloudstack/pull/10860 +.. _`#11388`: https://github.com/apache/cloudstack/pull/11388 +.. _`#11384`: https://github.com/apache/cloudstack/pull/11384 +.. _`#11373`: https://github.com/apache/cloudstack/pull/11373 +.. _`#9733`: https://github.com/apache/cloudstack/pull/9733 +.. _`#9478`: https://github.com/apache/cloudstack/pull/9478 +.. _`#11366`: https://github.com/apache/cloudstack/pull/11366 +.. _`#11197`: https://github.com/apache/cloudstack/pull/11197 +.. _`#11315`: https://github.com/apache/cloudstack/pull/11315 +.. _`#11380`: https://github.com/apache/cloudstack/pull/11380 +.. _`#11298`: https://github.com/apache/cloudstack/pull/11298 +.. _`#11181`: https://github.com/apache/cloudstack/pull/11181 +.. _`#11115`: https://github.com/apache/cloudstack/pull/11115 +.. _`#11372`: https://github.com/apache/cloudstack/pull/11372 +.. _`#11377`: https://github.com/apache/cloudstack/pull/11377 +.. _`#11016`: https://github.com/apache/cloudstack/pull/11016 +.. _`#11374`: https://github.com/apache/cloudstack/pull/11374 +.. _`#11349`: https://github.com/apache/cloudstack/pull/11349 +.. _`#11254`: https://github.com/apache/cloudstack/pull/11254 +.. _`#11369`: https://github.com/apache/cloudstack/pull/11369 +.. _`#11370`: https://github.com/apache/cloudstack/pull/11370 +.. _`#11291`: https://github.com/apache/cloudstack/pull/11291 +.. _`#11355`: https://github.com/apache/cloudstack/pull/11355 +.. _`#11164`: https://github.com/apache/cloudstack/pull/11164 +.. _`#11107`: https://github.com/apache/cloudstack/pull/11107 +.. _`#11340`: https://github.com/apache/cloudstack/pull/11340 +.. _`#11313`: https://github.com/apache/cloudstack/pull/11313 +.. _`#11353`: https://github.com/apache/cloudstack/pull/11353 +.. _`#10946`: https://github.com/apache/cloudstack/pull/10946 +.. _`#11177`: https://github.com/apache/cloudstack/pull/11177 +.. _`#11070`: https://github.com/apache/cloudstack/pull/11070 +.. _`#10140`: https://github.com/apache/cloudstack/pull/10140 +.. _`#10902`: https://github.com/apache/cloudstack/pull/10902 +.. _`#11337`: https://github.com/apache/cloudstack/pull/11337 +.. _`#11354`: https://github.com/apache/cloudstack/pull/11354 +.. _`#11352`: https://github.com/apache/cloudstack/pull/11352 +.. _`#11343`: https://github.com/apache/cloudstack/pull/11343 +.. _`#11330`: https://github.com/apache/cloudstack/pull/11330 +.. _`#11223`: https://github.com/apache/cloudstack/pull/11223 +.. _`#11142`: https://github.com/apache/cloudstack/pull/11142 +.. _`#11316`: https://github.com/apache/cloudstack/pull/11316 +.. _`#11342`: https://github.com/apache/cloudstack/pull/11342 +.. _`#11317`: https://github.com/apache/cloudstack/pull/11317 +.. _`#11245`: https://github.com/apache/cloudstack/pull/11245 +.. _`#11306`: https://github.com/apache/cloudstack/pull/11306 +.. _`#11332`: https://github.com/apache/cloudstack/pull/11332 +.. _`#11119`: https://github.com/apache/cloudstack/pull/11119 +.. _`#11310`: https://github.com/apache/cloudstack/pull/11310 +.. _`#11328`: https://github.com/apache/cloudstack/pull/11328 +.. _`#11068`: https://github.com/apache/cloudstack/pull/11068 +.. _`#11249`: https://github.com/apache/cloudstack/pull/11249 +.. _`#11143`: https://github.com/apache/cloudstack/pull/11143 +.. _`#11311`: https://github.com/apache/cloudstack/pull/11311 +.. _`#11244`: https://github.com/apache/cloudstack/pull/11244 +.. _`#11303`: https://github.com/apache/cloudstack/pull/11303 +.. _`#11200`: https://github.com/apache/cloudstack/pull/11200 +.. _`#11307`: https://github.com/apache/cloudstack/pull/11307 +.. _`#11302`: https://github.com/apache/cloudstack/pull/11302 +.. _`#11309`: https://github.com/apache/cloudstack/pull/11309 +.. _`#11042`: https://github.com/apache/cloudstack/pull/11042 +.. _`#11237`: https://github.com/apache/cloudstack/pull/11237 +.. _`#11239`: https://github.com/apache/cloudstack/pull/11239 +.. _`#9752`: https://github.com/apache/cloudstack/pull/9752 +.. _`#11232`: https://github.com/apache/cloudstack/pull/11232 +.. _`#11195`: https://github.com/apache/cloudstack/pull/11195 +.. _`#11292`: https://github.com/apache/cloudstack/pull/11292 +.. _`#10986`: https://github.com/apache/cloudstack/pull/10986 +.. _`#11220`: https://github.com/apache/cloudstack/pull/11220 +.. _`#11210`: https://github.com/apache/cloudstack/pull/11210 +.. _`#11053`: https://github.com/apache/cloudstack/pull/11053 +.. _`#10458`: https://github.com/apache/cloudstack/pull/10458 +.. _`#11264`: https://github.com/apache/cloudstack/pull/11264 +.. _`#11256`: https://github.com/apache/cloudstack/pull/11256 +.. _`#11276`: https://github.com/apache/cloudstack/pull/11276 +.. _`#10975`: https://github.com/apache/cloudstack/pull/10975 +.. _`#10856`: https://github.com/apache/cloudstack/pull/10856 +.. _`#10935`: https://github.com/apache/cloudstack/pull/10935 +.. _`#11221`: https://github.com/apache/cloudstack/pull/11221 +.. _`#11207`: https://github.com/apache/cloudstack/pull/11207 +.. _`#10736`: https://github.com/apache/cloudstack/pull/10736 +.. _`#11102`: https://github.com/apache/cloudstack/pull/11102 +.. _`#10966`: https://github.com/apache/cloudstack/pull/10966 +.. _`#11075`: https://github.com/apache/cloudstack/pull/11075 +.. _`#11087`: https://github.com/apache/cloudstack/pull/11087 +.. _`#11086`: https://github.com/apache/cloudstack/pull/11086 +.. _`#11064`: https://github.com/apache/cloudstack/pull/11064 +.. _`#11067`: https://github.com/apache/cloudstack/pull/11067 +.. _`#11066`: https://github.com/apache/cloudstack/pull/11066 +.. _`#11265`: https://github.com/apache/cloudstack/pull/11265 +.. _`#11258`: https://github.com/apache/cloudstack/pull/11258 +.. _`#11204`: https://github.com/apache/cloudstack/pull/11204 +.. _`#11093`: https://github.com/apache/cloudstack/pull/11093 +.. _`#11196`: https://github.com/apache/cloudstack/pull/11196 +.. _`#11261`: https://github.com/apache/cloudstack/pull/11261 +.. _`#11222`: https://github.com/apache/cloudstack/pull/11222 +.. _`#10857`: https://github.com/apache/cloudstack/pull/10857 +.. _`#11211`: https://github.com/apache/cloudstack/pull/11211 +.. _`#11215`: https://github.com/apache/cloudstack/pull/11215 +.. _`#11180`: https://github.com/apache/cloudstack/pull/11180 +.. _`#11214`: https://github.com/apache/cloudstack/pull/11214 +.. _`#10879`: https://github.com/apache/cloudstack/pull/10879 +.. _`#11138`: https://github.com/apache/cloudstack/pull/11138 +.. _`#11231`: https://github.com/apache/cloudstack/pull/11231 +.. _`#11054`: https://github.com/apache/cloudstack/pull/11054 +.. _`#10917`: https://github.com/apache/cloudstack/pull/10917 +.. _`#11101`: https://github.com/apache/cloudstack/pull/11101 +.. _`#11179`: https://github.com/apache/cloudstack/pull/11179 +.. _`#10947`: https://github.com/apache/cloudstack/pull/10947 +.. _`#11099`: https://github.com/apache/cloudstack/pull/11099 +.. _`#10632`: https://github.com/apache/cloudstack/pull/10632 +.. _`#11097`: https://github.com/apache/cloudstack/pull/11097 +.. _`#11047`: https://github.com/apache/cloudstack/pull/11047 +.. _`#11063`: https://github.com/apache/cloudstack/pull/11063 +.. _`#11191`: https://github.com/apache/cloudstack/pull/11191 +.. _`#11128`: https://github.com/apache/cloudstack/pull/11128 +.. _`#10997`: https://github.com/apache/cloudstack/pull/10997 +.. _`#8942`: https://github.com/apache/cloudstack/pull/8942 +.. _`#10575`: https://github.com/apache/cloudstack/pull/10575 +.. _`#10848`: https://github.com/apache/cloudstack/pull/10848 +.. _`#10503`: https://github.com/apache/cloudstack/pull/10503 +.. _`#11109`: https://github.com/apache/cloudstack/pull/11109 +.. _`#11171`: https://github.com/apache/cloudstack/pull/11171 +.. _`#10504`: https://github.com/apache/cloudstack/pull/10504 +.. _`#10576`: https://github.com/apache/cloudstack/pull/10576 +.. _`#11170`: https://github.com/apache/cloudstack/pull/11170 +.. _`#11158`: https://github.com/apache/cloudstack/pull/11158 +.. _`#11168`: https://github.com/apache/cloudstack/pull/11168 +.. _`#11091`: https://github.com/apache/cloudstack/pull/11091 +.. _`#11113`: https://github.com/apache/cloudstack/pull/11113 +.. _`#10951`: https://github.com/apache/cloudstack/pull/10951 +.. _`#10899`: https://github.com/apache/cloudstack/pull/10899 +.. _`#10778`: https://github.com/apache/cloudstack/pull/10778 +.. _`#10325`: https://github.com/apache/cloudstack/pull/10325 +.. _`#11003`: https://github.com/apache/cloudstack/pull/11003 +.. _`#11116`: https://github.com/apache/cloudstack/pull/11116 +.. _`#11095`: https://github.com/apache/cloudstack/pull/11095 +.. _`#11085`: https://github.com/apache/cloudstack/pull/11085 +.. _`#10995`: https://github.com/apache/cloudstack/pull/10995 +.. _`#11106`: https://github.com/apache/cloudstack/pull/11106 +.. _`#11004`: https://github.com/apache/cloudstack/pull/11004 +.. _`#11069`: https://github.com/apache/cloudstack/pull/11069 +.. _`#11060`: https://github.com/apache/cloudstack/pull/11060 +.. _`#11019`: https://github.com/apache/cloudstack/pull/11019 +.. _`#11035`: https://github.com/apache/cloudstack/pull/11035 +.. _`#11057`: https://github.com/apache/cloudstack/pull/11057 +.. _`#11055`: https://github.com/apache/cloudstack/pull/11055 +.. _`#9102`: https://github.com/apache/cloudstack/pull/9102 +.. _`#11040`: https://github.com/apache/cloudstack/pull/11040 +.. _`#9277`: https://github.com/apache/cloudstack/pull/9277 +.. _`#11025`: https://github.com/apache/cloudstack/pull/11025 +.. _`#11013`: https://github.com/apache/cloudstack/pull/11013 +.. _`#10475`: https://github.com/apache/cloudstack/pull/10475 +.. _`#10077`: https://github.com/apache/cloudstack/pull/10077 +.. _`#9833`: https://github.com/apache/cloudstack/pull/9833 +.. _`#10896`: https://github.com/apache/cloudstack/pull/10896 +.. _`#10987`: https://github.com/apache/cloudstack/pull/10987 +.. _`#9969`: https://github.com/apache/cloudstack/pull/9969 +.. _`#11011`: https://github.com/apache/cloudstack/pull/11011 +.. _`#11012`: https://github.com/apache/cloudstack/pull/11012 +.. _`#11001`: https://github.com/apache/cloudstack/pull/11001 +.. _`#11010`: https://github.com/apache/cloudstack/pull/11010 +.. _`#10587`: https://github.com/apache/cloudstack/pull/10587 +.. _`#10663`: https://github.com/apache/cloudstack/pull/10663 +.. _`#10773`: https://github.com/apache/cloudstack/pull/10773 +.. _`#10814`: https://github.com/apache/cloudstack/pull/10814 +.. _`#10949`: https://github.com/apache/cloudstack/pull/10949 +.. _`#10769`: https://github.com/apache/cloudstack/pull/10769 + +Changes in |release| since 4.20.0.0 +=================================== + +Apache CloudStack uses GitHub https://github.com/apache/cloudstack/milestone/36?closed=1 +to track its issues. + + +.. cssclass:: table-striped table-bordered table-hover + ++-------------------------+--------------------+------------------------------------------------------------+ +| Version | Github | Description | ++=========================+====================+============================================================+ +| 4.20.1.0 | `#10927`_ | systemvmtemplate: fix Debian 12.11.0 ISO url | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10916`_ | server: fix list diskoffering by domainid returns Inactive | +| | | offerings | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10861`_ | Routed: support vxlan networks | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10912`_ | Fix issue with configdrive on XenServer | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10843`_ | backport #10744: engine/schema: create default network | +| | | offering for vpc tier with conserve_mode=1 for fresh | +| | | installation | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10894`_ | .github: fix sonar checks | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10882`_ | Fixed some typos | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10893`_ | test: cleanup acl in test_global_acls.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10891`_ | mgmt: add back serviceip in ManagementServerResponse | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10875`_ | Address `assignVm` regression | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10890`_ | test: fix several simulator CI failures | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10885`_ | test: fix test_restore_vm failure on vmware | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10881`_ | test: Update test ubuntu template for VMware to | +| | | deployasis=False | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10586`_ | VMware 80u2 and 80u3 updates/fixes | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10878`_ | linstor: fix host connect recursion regression | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10849`_ | Fix issue with security group selection box display | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10840`_ | ui: add an infinite scroll select component | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10777`_ | Reset the pool id when create volume fails on the | +| | | allocated pool, and update the resize error when no | +| | | endpoint exists | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10799`_ | Prevent data corruption for StorPool volumes | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10837`_ | Fix for Vlan doesn't match issue while adding IP range for | +| | | the shared network without any IP range | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10876`_ | Correct typo in an exception message | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10433`_ | VMware import - logs sanitation | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10253`_ | ssvm: reset fields on destroy | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10867`_ | ui: Assign/Remove Backup offering buttons incorrect in | +| | | details view | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10844`_ | NAS BnR: Restore backed-up volume on live instances is not | +| | | readable | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10852`_ | List usage records for network offering (usage type 13) | +| | | when offering id is specified in usage id | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10770`_ | [Vmware] Improve listing of Vmware Datacenter VMs for | +| | | migration to KVM | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10757`_ | Updated Endpoint Selector to pick the Cluster in Enabled | +| | | state (in addition to Host state) | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10674`_ | Direct agents rebalance improvements with multiple | +| | | management server nodes | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10684`_ | Support XenServer 8.4 / XCP 8.3 - make scripts python3 | +| | | compatible | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10850`_ | Linstor: implement volume and storage stats | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10061`_ | enhancement: add password to configdrive vendor_data.json | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10748`_ | [VMware] Sync the disk path or datastore changes for IDE | +| | | disks, and before any volume resize during start vm (for | +| | | the volumes on datastore cluster) | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10544`_ | refactor create duplicate alert check | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10820`_ | core: support chunked transfer for image files | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10612`_ | server: check if redundant router is supported when | +| | | restart network with makeredundant = true | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10833`_ | xenserver: destroy halted vm on expunge | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10807`_ | cleanup call on super in affinity groups projects | +| | | component test | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10775`_ | StorPool notify libvirt when volume is resized | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#9825`_ | ui: improve metrics api use in list views | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10744`_ | engine/schema: create default network offering for vpc | +| | | tier with conserve_mode=1 for fresh installation | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10431`_ | server: fetch IP of VMs on L2 networks | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10824`_ | UI workaround for the inconsistent formatting of | +| | | listVirtualMachinesUsageHistory | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10712`_ | Backport #9888 to 4.19: Fix Usage inconsistencies | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10822`_ | Add search bar on rules of roles | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10785`_ | Nas BnR: Fix for restore not working correctly | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10815`_ | test: fix test_hostha_simulator.py and | +| | | test_outofbandmanagement.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10708`_ | [VMware] Update vlans with proper range before creating | +| | | port group for dvSwitch | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10818`_ | test: cleanup test_guest_os.py for multiple execution | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10624`_ | server: prevent duplicate HA works and alerts | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10806`_ | smoke tests / CI : Fix test_vm_stric_host_tags | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10760`_ | Extra checks in UI when deleting accounts | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10805`_ | Update dependency required for test_outofbandmanagement.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10629`_ | check for custom offering and trim size | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10265`_ | [UI] Allow quiescevm and asyncbackup flags while taking | +| | | volume snapshot from UI when these are supported for the | +| | | volume | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10241`_ | server: apply network ACL even if there is no network ACLs | +| | | in the ACL list (#9374) | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10725`_ | UI: show checksum field when register or upload | +| | | template/isos | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10714`_ | UI: Allow editing a Running VM in an Advanced zone with | +| | | security groups except for security group details | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10772`_ | Ceph object store: Fix LocationConstraint error | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10791`_ | UI: Display system VM count in hosts listing | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10726`_ | cloudutils: use "ip route" command instead of "route -n" | +| | | in networkConfig.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10749`_ | ResourceCleanupService test fix for daylight saving time | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10774`_ | Xenserver smoke-test: Allow emojis to be accepted in | +| | | volume name during volume creation | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10525`_ | Add new config (non-dynamic) for agent connections | +| | | monitor thread, and keep timeunit to secs (in sync with | +| | | the earlier Wait config) | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10761`_ | smoke tests: Fix cluster DRS & non-strict host affinity | +| | | smoke test failures on XenServer / XCP-ng | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10755`_ | Network Usage event model adjustments | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10543`_ | vTPM: support KVM and VMware | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10583`_ | Fix smoke tests due to change in behavior of restore VM | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10289`_ | api,ui: multi arch improvements | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10741`_ | Smoke tests: Xenserver - Fix consistent failure noticed on | +| | | scale VM test | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10762`_ | test: fix test_certauthority_root.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10746`_ | Don't specify ipv6 ranges for shared network | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10647`_ | Revert "Add the option to filter by host when retrieving | +| | | of unregistered VMs (#9925)" | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10738`_ | server: fix available hypervisors listing for a zone | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10662`_ | Fix the size of a template downloaded from secondary | +| | | storage | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10745`_ | ui: confirm on reset configurations | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10493`_ | Fix NPE on updating security groups for an instance | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10603`_ | Fix issue with allocator not considering subsequent | +| | | clusters | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10568`_ | Remove the validation of the amount of acquired public IPs | +| | | when enabling static NAT, adding PF and LB rules on VPC | +| | | public IPs | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10750`_ | UI: Update message of load balancer for autoscaling group | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10753`_ | .github: fix simulator CI caused by imcompatibility | +| | | between python3.10 and nosetests | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10739`_ | VR: add bind-interfaces to /etc/dnsmasq.d/cloud.conf | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10717`_ | plugin/shutdown: use mgmt server uuid in the shutdown | +| | | response | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10630`_ | utils: fix extra slash in Redfish default systems url path | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10728`_ | only clean details and annotations when this template no | +| | | longer exists | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10591`_ | HA: set correct hostId of HA work for vm migration | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10709`_ | UI: Move templates creation date to the Zones tab | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10704`_ | server: check startip and startipv6 of shared network | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10495`_ | Support ConfigDrive with VPC | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10707`_ | Fix volume migration failure handling | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10702`_ | Backport #10273 to `4.20`: Grant access to 2FA APIs for | +| | | default read-only and support roles | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10364`_ | Migrate public templates that have URLs on data migration | +| | | across secondary storages | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10564`_ | Add download link of volumes, templates and ISOs to the | +| | | download event details | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10700`_ | UI: Fix column name in Usage view | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10311`_ | 4.19 fix saml account selector | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10649`_ | Usage server: remove logging of prameters including secret | +| | | keys | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10567`_ | undo removal of accessLogger and deal with some warnings | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10580`_ | UI: Restore AS Numbers and IPv4 Subnets menus | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10653`_ | Backport #10500 framework/cluster: fix NPE for ms-host | +| | | status when mgr stops | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#9175`_ | xenserver: do not destroy halted hypervisor vm | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10652`_ | UI: Allow setting account and domain maximum amount of | +| | | projects through the UI | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10651`_ | UI: Fix projects metrics on dashboard | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10628`_ | systemvm: Bump systemvm template version to debian 12.10 | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10617`_ | Enhance VPC Network Tier form to auto-populate Gateway, | +| | | and Netmask | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10263`_ | Updated setup-sysvm-tmplt script, to run cmds accessing | +| | | destdir with sudo | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10613`_ | enhancement: Optimize listZonesMetrics and | +| | | listClustersMetrics call performance | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10496`_ | Preview-Experimental Support EL10 as Management Server and | +| | | KVM host | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10606`_ | Host status auto refresh | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10595`_ | UI: fix list of vpc network offerings | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10602`_ | ui: fix considerlasthost for start vm | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10546`_ | Fix secondary storage selectors feature | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10513`_ | framework-config: improve configkey caching | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10559`_ | Update ubuntu image link for template download | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10524`_ | Fix to propagate updated management servers list and lb | +| | | algorithm in host and indirect.agent.lb.algorithm settings | +| | | resp, to systemvm agents | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10518`_ | deal with null return for create deployment plan for | +| | | maintenance | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10561`_ | linstor: implement missing deleteDatastore | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10563`_ | api: fix EntityReference in NetworkResponse.java | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10366`_ | server: fix npe during start vr edge case | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10569`_ | List only VMs associated to a userdata | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10562`_ | Veeam BnR : Fix for error in remove backup offering | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10492`_ | Fix Stats Collector to not divide by zero | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10443`_ | linstor: try to delete -rst resource before snapshot | +| | | backup | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10516`_ | kvm: find cluster-wide pools only in Up state when | +| | | investigate a host | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10515`_ | KVM: return null state instead of Disconnected when | +| | | investigate a host without NFS | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10257`_ | VPC: fix private mtu of vpc tier | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10461`_ | UI: Allow custom footer in password reset page | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10450`_ | fix: prometheus: don't poll the same tag multiple times | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10501`_ | test: fix failure in | +| | | test_06_purge_expunged_vm_background_task | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10502`_ | lint: fix test_linstor_volumes.py | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#8831`_ | Refactor alert email generation method | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10497`_ | ui: do not cache config.json and locale files | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#9666`_ | NAS B&R Plugin enhancements | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10474`_ | Remove isMirrored parameter when creating a disk offering | +| | | through UI | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10042`_ | UI: Proper explanation for the global setting to avoid | +| | | ambiguity | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10484`_ | UI: Show Host OOBM parameter in form if configured | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10472`_ | UI: List host OOBM details when enabled and configured | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10455`_ | UI: Filter accounts by domain while creating templates - | +| | | from Volume / Snapshot | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10439`_ | linstor: improve integration-tests | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10337`_ | UI: Add change host password | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#8575`_ | removing the usage of volumeFreeze StorPool API call | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10476`_ | Fix listing disk offerings for newly created VMs that | +| | | haven't yet been started | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10466`_ | cloudstack-setup-databases: fix mode and group of key file | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10376`_ | add use of virsh domifaddr to get VM external DHCP IP | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10462`_ | systemvmtemplate: bump version Debian 12.9.0 and ACS | +| | | 4.20.1 | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10266`_ | kvm: fix volume migration across cluster-scope pools | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10351`_ | UI: Fixes and minor enhacements to the Public IP Addresses | +| | | section | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10221`_ | fix: enforce the minimum cgroup cpu shares value to 2 | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10425`_ | UI: Fix filtering of templates by account | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10407`_ | engine/orchestration: fix missing vm powerstate update vm | +| | | state | ++-------------------------+--------------------+------------------------------------------------------------+ +| 4.20.1.0 | `#10418`_ | Fix hostId verification on unsuccessful expunge operation | ++-------------------------+--------------------+------------------------------------------------------------+ + +150 Issues listed + +.. _`#10927`: https://github.com/apache/cloudstack/pull/10927 +.. _`#10916`: https://github.com/apache/cloudstack/pull/10916 +.. _`#10861`: https://github.com/apache/cloudstack/pull/10861 +.. _`#10912`: https://github.com/apache/cloudstack/pull/10912 +.. _`#10843`: https://github.com/apache/cloudstack/pull/10843 +.. _`#10894`: https://github.com/apache/cloudstack/pull/10894 +.. _`#10882`: https://github.com/apache/cloudstack/pull/10882 +.. _`#10893`: https://github.com/apache/cloudstack/pull/10893 +.. _`#10891`: https://github.com/apache/cloudstack/pull/10891 +.. _`#10875`: https://github.com/apache/cloudstack/pull/10875 +.. _`#10890`: https://github.com/apache/cloudstack/pull/10890 +.. _`#10885`: https://github.com/apache/cloudstack/pull/10885 +.. _`#10881`: https://github.com/apache/cloudstack/pull/10881 +.. _`#10586`: https://github.com/apache/cloudstack/pull/10586 +.. _`#10878`: https://github.com/apache/cloudstack/pull/10878 +.. _`#10849`: https://github.com/apache/cloudstack/pull/10849 +.. _`#10840`: https://github.com/apache/cloudstack/pull/10840 +.. _`#10777`: https://github.com/apache/cloudstack/pull/10777 +.. _`#10799`: https://github.com/apache/cloudstack/pull/10799 +.. _`#10837`: https://github.com/apache/cloudstack/pull/10837 +.. _`#10876`: https://github.com/apache/cloudstack/pull/10876 +.. _`#10433`: https://github.com/apache/cloudstack/pull/10433 +.. _`#10253`: https://github.com/apache/cloudstack/pull/10253 +.. _`#10867`: https://github.com/apache/cloudstack/pull/10867 +.. _`#10844`: https://github.com/apache/cloudstack/pull/10844 +.. _`#10852`: https://github.com/apache/cloudstack/pull/10852 +.. _`#10770`: https://github.com/apache/cloudstack/pull/10770 +.. _`#10757`: https://github.com/apache/cloudstack/pull/10757 +.. _`#10674`: https://github.com/apache/cloudstack/pull/10674 +.. _`#10684`: https://github.com/apache/cloudstack/pull/10684 +.. _`#10850`: https://github.com/apache/cloudstack/pull/10850 +.. _`#10061`: https://github.com/apache/cloudstack/pull/10061 +.. _`#10748`: https://github.com/apache/cloudstack/pull/10748 +.. _`#10544`: https://github.com/apache/cloudstack/pull/10544 +.. _`#10820`: https://github.com/apache/cloudstack/pull/10820 +.. _`#10612`: https://github.com/apache/cloudstack/pull/10612 +.. _`#10833`: https://github.com/apache/cloudstack/pull/10833 +.. _`#10807`: https://github.com/apache/cloudstack/pull/10807 +.. _`#10775`: https://github.com/apache/cloudstack/pull/10775 +.. _`#9825`: https://github.com/apache/cloudstack/pull/9825 +.. _`#10744`: https://github.com/apache/cloudstack/pull/10744 +.. _`#10431`: https://github.com/apache/cloudstack/pull/10431 +.. _`#10824`: https://github.com/apache/cloudstack/pull/10824 +.. _`#10712`: https://github.com/apache/cloudstack/pull/10712 +.. _`#10822`: https://github.com/apache/cloudstack/pull/10822 +.. _`#10785`: https://github.com/apache/cloudstack/pull/10785 +.. _`#10815`: https://github.com/apache/cloudstack/pull/10815 +.. _`#10708`: https://github.com/apache/cloudstack/pull/10708 +.. _`#10818`: https://github.com/apache/cloudstack/pull/10818 +.. _`#10624`: https://github.com/apache/cloudstack/pull/10624 +.. _`#10806`: https://github.com/apache/cloudstack/pull/10806 +.. _`#10760`: https://github.com/apache/cloudstack/pull/10760 +.. _`#10805`: https://github.com/apache/cloudstack/pull/10805 +.. _`#10629`: https://github.com/apache/cloudstack/pull/10629 +.. _`#10265`: https://github.com/apache/cloudstack/pull/10265 +.. _`#10241`: https://github.com/apache/cloudstack/pull/10241 +.. _`#10725`: https://github.com/apache/cloudstack/pull/10725 +.. _`#10714`: https://github.com/apache/cloudstack/pull/10714 +.. _`#10772`: https://github.com/apache/cloudstack/pull/10772 +.. _`#10791`: https://github.com/apache/cloudstack/pull/10791 +.. _`#10726`: https://github.com/apache/cloudstack/pull/10726 +.. _`#10749`: https://github.com/apache/cloudstack/pull/10749 +.. _`#10774`: https://github.com/apache/cloudstack/pull/10774 +.. _`#10525`: https://github.com/apache/cloudstack/pull/10525 +.. _`#10761`: https://github.com/apache/cloudstack/pull/10761 +.. _`#10755`: https://github.com/apache/cloudstack/pull/10755 +.. _`#10543`: https://github.com/apache/cloudstack/pull/10543 +.. _`#10583`: https://github.com/apache/cloudstack/pull/10583 +.. _`#10289`: https://github.com/apache/cloudstack/pull/10289 +.. _`#10741`: https://github.com/apache/cloudstack/pull/10741 +.. _`#10762`: https://github.com/apache/cloudstack/pull/10762 +.. _`#10746`: https://github.com/apache/cloudstack/pull/10746 +.. _`#10647`: https://github.com/apache/cloudstack/pull/10647 +.. _`#10738`: https://github.com/apache/cloudstack/pull/10738 +.. _`#10662`: https://github.com/apache/cloudstack/pull/10662 +.. _`#10745`: https://github.com/apache/cloudstack/pull/10745 +.. _`#10493`: https://github.com/apache/cloudstack/pull/10493 +.. _`#10603`: https://github.com/apache/cloudstack/pull/10603 +.. _`#10568`: https://github.com/apache/cloudstack/pull/10568 +.. _`#10750`: https://github.com/apache/cloudstack/pull/10750 +.. _`#10753`: https://github.com/apache/cloudstack/pull/10753 +.. _`#10739`: https://github.com/apache/cloudstack/pull/10739 +.. _`#10717`: https://github.com/apache/cloudstack/pull/10717 +.. _`#10630`: https://github.com/apache/cloudstack/pull/10630 +.. _`#10728`: https://github.com/apache/cloudstack/pull/10728 +.. _`#10591`: https://github.com/apache/cloudstack/pull/10591 +.. _`#10709`: https://github.com/apache/cloudstack/pull/10709 +.. _`#10704`: https://github.com/apache/cloudstack/pull/10704 +.. _`#10495`: https://github.com/apache/cloudstack/pull/10495 +.. _`#10707`: https://github.com/apache/cloudstack/pull/10707 +.. _`#10702`: https://github.com/apache/cloudstack/pull/10702 +.. _`#10364`: https://github.com/apache/cloudstack/pull/10364 +.. _`#10564`: https://github.com/apache/cloudstack/pull/10564 +.. _`#10700`: https://github.com/apache/cloudstack/pull/10700 +.. _`#10311`: https://github.com/apache/cloudstack/pull/10311 +.. _`#10649`: https://github.com/apache/cloudstack/pull/10649 +.. _`#10567`: https://github.com/apache/cloudstack/pull/10567 +.. _`#10580`: https://github.com/apache/cloudstack/pull/10580 +.. _`#10653`: https://github.com/apache/cloudstack/pull/10653 +.. _`#9175`: https://github.com/apache/cloudstack/pull/9175 +.. _`#10652`: https://github.com/apache/cloudstack/pull/10652 +.. _`#10651`: https://github.com/apache/cloudstack/pull/10651 +.. _`#10628`: https://github.com/apache/cloudstack/pull/10628 +.. _`#10617`: https://github.com/apache/cloudstack/pull/10617 +.. _`#10263`: https://github.com/apache/cloudstack/pull/10263 +.. _`#10613`: https://github.com/apache/cloudstack/pull/10613 +.. _`#10496`: https://github.com/apache/cloudstack/pull/10496 +.. _`#10606`: https://github.com/apache/cloudstack/pull/10606 +.. _`#10595`: https://github.com/apache/cloudstack/pull/10595 +.. _`#10602`: https://github.com/apache/cloudstack/pull/10602 +.. _`#10546`: https://github.com/apache/cloudstack/pull/10546 +.. _`#10513`: https://github.com/apache/cloudstack/pull/10513 +.. _`#10559`: https://github.com/apache/cloudstack/pull/10559 +.. _`#10524`: https://github.com/apache/cloudstack/pull/10524 +.. _`#10518`: https://github.com/apache/cloudstack/pull/10518 +.. _`#10561`: https://github.com/apache/cloudstack/pull/10561 +.. _`#10563`: https://github.com/apache/cloudstack/pull/10563 +.. _`#10366`: https://github.com/apache/cloudstack/pull/10366 +.. _`#10569`: https://github.com/apache/cloudstack/pull/10569 +.. _`#10562`: https://github.com/apache/cloudstack/pull/10562 +.. _`#10492`: https://github.com/apache/cloudstack/pull/10492 +.. _`#10443`: https://github.com/apache/cloudstack/pull/10443 +.. _`#10516`: https://github.com/apache/cloudstack/pull/10516 +.. _`#10515`: https://github.com/apache/cloudstack/pull/10515 +.. _`#10257`: https://github.com/apache/cloudstack/pull/10257 +.. _`#10461`: https://github.com/apache/cloudstack/pull/10461 +.. _`#10450`: https://github.com/apache/cloudstack/pull/10450 +.. _`#10501`: https://github.com/apache/cloudstack/pull/10501 +.. _`#10502`: https://github.com/apache/cloudstack/pull/10502 +.. _`#8831`: https://github.com/apache/cloudstack/pull/8831 +.. _`#10497`: https://github.com/apache/cloudstack/pull/10497 +.. _`#9666`: https://github.com/apache/cloudstack/pull/9666 +.. _`#10474`: https://github.com/apache/cloudstack/pull/10474 +.. _`#10042`: https://github.com/apache/cloudstack/pull/10042 +.. _`#10484`: https://github.com/apache/cloudstack/pull/10484 +.. _`#10472`: https://github.com/apache/cloudstack/pull/10472 +.. _`#10455`: https://github.com/apache/cloudstack/pull/10455 +.. _`#10439`: https://github.com/apache/cloudstack/pull/10439 +.. _`#10337`: https://github.com/apache/cloudstack/pull/10337 +.. _`#8575`: https://github.com/apache/cloudstack/pull/8575 +.. _`#10476`: https://github.com/apache/cloudstack/pull/10476 +.. _`#10466`: https://github.com/apache/cloudstack/pull/10466 +.. _`#10376`: https://github.com/apache/cloudstack/pull/10376 +.. _`#10462`: https://github.com/apache/cloudstack/pull/10462 +.. _`#10266`: https://github.com/apache/cloudstack/pull/10266 +.. _`#10351`: https://github.com/apache/cloudstack/pull/10351 +.. _`#10221`: https://github.com/apache/cloudstack/pull/10221 +.. _`#10425`: https://github.com/apache/cloudstack/pull/10425 +.. _`#10407`: https://github.com/apache/cloudstack/pull/10407 +.. _`#10418`: https://github.com/apache/cloudstack/pull/10418 + + +Changes in |release| since 4.19.1.0 +=================================== + +Apache CloudStack uses GitHub https://github.com/apache/cloudstack/milestone/30?closed=1 to track its issues. + +.. cssclass:: table-striped table-bordered table-hover + + ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| Version | Github | Type | Priority | Description | ++=========================+============+===============+==========+============================================================+ +| 4.19.3.0 | `#10916`_ | | | server: fix list diskoffering by domainid returns Inactive | +| | | | | offerings | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10912`_ | | | Fix issue with configdrive on XenServer | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10843`_ | | | backport #10744: engine/schema: create default network | +| | | | | offering for vpc tier with conserve_mode=1 for fresh | +| | | | | installation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10882`_ | | | Fixed some typos | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10893`_ | | | test: cleanup acl in test_global_acls.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10849`_ | | | Fix issue with security group selection box display | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10840`_ | | | ui: add an infinite scroll select component | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10777`_ | | | Reset the pool id when create volume fails on the | +| | | | | allocated pool, and update the resize error when no | +| | | | | endpoint exists | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10799`_ | | | Prevent data corruption for StorPool volumes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10837`_ | | | Fix for Vlan doesn't match issue while adding IP range for | +| | | | | the shared network without any IP range | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10876`_ | | | Correct typo in an exception message | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10433`_ | | | VMware import - logs sanitation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10253`_ | | | ssvm: reset fields on destroy | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10852`_ | | | List usage records for network offering (usage type 13) | +| | | | | when offering id is specified in usage id | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10770`_ | | | [Vmware] Improve listing of Vmware Datacenter VMs for | +| | | | | migration to KVM | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10850`_ | | | Linstor: implement volume and storage stats | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10748`_ | | | [VMware] Sync the disk path or datastore changes for IDE | +| | | | | disks, and before any volume resize during start vm (for | +| | | | | the volumes on datastore cluster) | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10544`_ | | | refactor create duplicate alert check | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10612`_ | | | server: check if redundant router is supported when | +| | | | | restart network with makeredundant = true | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10833`_ | | | xenserver: destroy halted vm on expunge | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10807`_ | | | cleanup call on super in affinity groups projects | +| | | | | component test | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10431`_ | | | server: fetch IP of VMs on L2 networks | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10824`_ | | | UI workaround for the inconsistent formatting of | +| | | | | listVirtualMachinesUsageHistory | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10712`_ | | | Backport #9888 to 4.19: Fix Usage inconsistencies | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10708`_ | | | [VMware] Update vlans with proper range before creating | +| | | | | port group for dvSwitch | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10624`_ | | | server: prevent duplicate HA works and alerts | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10760`_ | | | Extra checks in UI when deleting accounts | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10805`_ | | | Update dependency required for test_outofbandmanagement.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10629`_ | | | check for custom offering and trim size | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10265`_ | | | [UI] Allow quiescevm and asyncbackup flags while taking | +| | | | | volume snapshot from UI when these are supported for the | +| | | | | volume | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10725`_ | | | UI: show checksum field when register or upload | +| | | | | template/isos | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10714`_ | | | UI: Allow editing a Running VM in an Advanced zone with | +| | | | | security groups except for security group details | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10726`_ | | | cloudutils: use "ip route" command instead of "route -n" | +| | | | | in networkConfig.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10761`_ | | | smoke tests: Fix cluster DRS & non-strict host affinity | +| | | | | smoke test failures on XenServer / XCP-ng | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10755`_ | | | Network Usage event model adjustments | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10583`_ | | | Fix smoke tests due to change in behavior of restore VM | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10762`_ | | | test: fix test_certauthority_root.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10746`_ | | | Don't specify ipv6 ranges for shared network | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10647`_ | | | Revert "Add the option to filter by host when retrieving | +| | | | | of unregistered VMs (#9925)" | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10745`_ | | | ui: confirm on reset configurations | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10568`_ | | | Remove the validation of the amount of acquired public IPs | +| | | | | when enabling static NAT, adding PF and LB rules on VPC | +| | | | | public IPs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10753`_ | | | .github: fix simulator CI caused by imcompatibility | +| | | | | between python3.10 and nosetests | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10739`_ | | | VR: add bind-interfaces to /etc/dnsmasq.d/cloud.conf | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10717`_ | | | plugin/shutdown: use mgmt server uuid in the shutdown | +| | | | | response | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10728`_ | | | only clean details and annotations when this template no | +| | | | | longer exists | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10591`_ | | | HA: set correct hostId of HA work for vm migration | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10709`_ | | | UI: Move templates creation date to the Zones tab | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10704`_ | | | server: check startip and startipv6 of shared network | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10311`_ | | | 4.19 fix saml account selector | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10649`_ | | | Usage server: remove logging of prameters including secret | +| | | | | keys | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10653`_ | | | Backport #10500 framework/cluster: fix NPE for ms-host | +| | | | | status when mgr stops | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#9175`_ | | | xenserver: do not destroy halted hypervisor vm | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10652`_ | | | UI: Allow setting account and domain maximum amount of | +| | | | | projects through the UI | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10651`_ | | | UI: Fix projects metrics on dashboard | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10617`_ | | | Enhance VPC Network Tier form to auto-populate Gateway, | +| | | | | and Netmask | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10263`_ | | | Updated setup-sysvm-tmplt script, to run cmds accessing | +| | | | | destdir with sudo | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10606`_ | | | Host status auto refresh | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10595`_ | | | UI: fix list of vpc network offerings | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10602`_ | | | ui: fix considerlasthost for start vm | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10518`_ | | | deal with null return for create deployment plan for | +| | | | | maintenance | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10561`_ | | | linstor: implement missing deleteDatastore | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10563`_ | | | api: fix EntityReference in NetworkResponse.java | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10366`_ | | | server: fix npe during start vr edge case | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10569`_ | | | List only VMs associated to a userdata | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10562`_ | | | Veeam BnR : Fix for error in remove backup offering | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10443`_ | | | linstor: try to delete -rst resource before snapshot | +| | | | | backup | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10516`_ | | | kvm: find cluster-wide pools only in Up state when | +| | | | | investigate a host | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10515`_ | | | KVM: return null state instead of Disconnected when | +| | | | | investigate a host without NFS | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10257`_ | | | VPC: fix private mtu of vpc tier | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10484`_ | | | UI: Show Host OOBM parameter in form if configured | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10472`_ | | | UI: List host OOBM details when enabled and configured | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10455`_ | | | UI: Filter accounts by domain while creating templates - | +| | | | | from Volume / Snapshot | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10439`_ | | | linstor: improve integration-tests | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10466`_ | | | cloudstack-setup-databases: fix mode and group of key file | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10376`_ | | | add use of virsh domifaddr to get VM external DHCP IP | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10266`_ | | | kvm: fix volume migration across cluster-scope pools | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10351`_ | | | UI: Fixes and minor enhacements to the Public IP Addresses | +| | | | | section | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.3.0 | `#10425`_ | | | UI: Fix filtering of templates by account | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ + +78 Issues listed + +.. _`#10916`: https://github.com/apache/cloudstack/pull/10916 +.. _`#10912`: https://github.com/apache/cloudstack/pull/10912 +.. _`#10843`: https://github.com/apache/cloudstack/pull/10843 +.. _`#10882`: https://github.com/apache/cloudstack/pull/10882 +.. _`#10893`: https://github.com/apache/cloudstack/pull/10893 +.. _`#10849`: https://github.com/apache/cloudstack/pull/10849 +.. _`#10840`: https://github.com/apache/cloudstack/pull/10840 +.. _`#10777`: https://github.com/apache/cloudstack/pull/10777 +.. _`#10799`: https://github.com/apache/cloudstack/pull/10799 +.. _`#10837`: https://github.com/apache/cloudstack/pull/10837 +.. _`#10876`: https://github.com/apache/cloudstack/pull/10876 +.. _`#10433`: https://github.com/apache/cloudstack/pull/10433 +.. _`#10253`: https://github.com/apache/cloudstack/pull/10253 +.. _`#10852`: https://github.com/apache/cloudstack/pull/10852 +.. _`#10770`: https://github.com/apache/cloudstack/pull/10770 +.. _`#10850`: https://github.com/apache/cloudstack/pull/10850 +.. _`#10748`: https://github.com/apache/cloudstack/pull/10748 +.. _`#10544`: https://github.com/apache/cloudstack/pull/10544 +.. _`#10612`: https://github.com/apache/cloudstack/pull/10612 +.. _`#10833`: https://github.com/apache/cloudstack/pull/10833 +.. _`#10807`: https://github.com/apache/cloudstack/pull/10807 +.. _`#10431`: https://github.com/apache/cloudstack/pull/10431 +.. _`#10824`: https://github.com/apache/cloudstack/pull/10824 +.. _`#10712`: https://github.com/apache/cloudstack/pull/10712 +.. _`#10708`: https://github.com/apache/cloudstack/pull/10708 +.. _`#10624`: https://github.com/apache/cloudstack/pull/10624 +.. _`#10760`: https://github.com/apache/cloudstack/pull/10760 +.. _`#10805`: https://github.com/apache/cloudstack/pull/10805 +.. _`#10629`: https://github.com/apache/cloudstack/pull/10629 +.. _`#10265`: https://github.com/apache/cloudstack/pull/10265 +.. _`#10725`: https://github.com/apache/cloudstack/pull/10725 +.. _`#10714`: https://github.com/apache/cloudstack/pull/10714 +.. _`#10726`: https://github.com/apache/cloudstack/pull/10726 +.. _`#10761`: https://github.com/apache/cloudstack/pull/10761 +.. _`#10755`: https://github.com/apache/cloudstack/pull/10755 +.. _`#10583`: https://github.com/apache/cloudstack/pull/10583 +.. _`#10762`: https://github.com/apache/cloudstack/pull/10762 +.. _`#10746`: https://github.com/apache/cloudstack/pull/10746 +.. _`#10647`: https://github.com/apache/cloudstack/pull/10647 +.. _`#10745`: https://github.com/apache/cloudstack/pull/10745 +.. _`#10568`: https://github.com/apache/cloudstack/pull/10568 +.. _`#10753`: https://github.com/apache/cloudstack/pull/10753 +.. _`#10739`: https://github.com/apache/cloudstack/pull/10739 +.. _`#10717`: https://github.com/apache/cloudstack/pull/10717 +.. _`#10728`: https://github.com/apache/cloudstack/pull/10728 +.. _`#10591`: https://github.com/apache/cloudstack/pull/10591 +.. _`#10709`: https://github.com/apache/cloudstack/pull/10709 +.. _`#10704`: https://github.com/apache/cloudstack/pull/10704 +.. _`#10311`: https://github.com/apache/cloudstack/pull/10311 +.. _`#10649`: https://github.com/apache/cloudstack/pull/10649 +.. _`#10653`: https://github.com/apache/cloudstack/pull/10653 +.. _`#9175`: https://github.com/apache/cloudstack/pull/9175 +.. _`#10652`: https://github.com/apache/cloudstack/pull/10652 +.. _`#10651`: https://github.com/apache/cloudstack/pull/10651 +.. _`#10617`: https://github.com/apache/cloudstack/pull/10617 +.. _`#10263`: https://github.com/apache/cloudstack/pull/10263 +.. _`#10606`: https://github.com/apache/cloudstack/pull/10606 +.. _`#10595`: https://github.com/apache/cloudstack/pull/10595 +.. _`#10602`: https://github.com/apache/cloudstack/pull/10602 +.. _`#10518`: https://github.com/apache/cloudstack/pull/10518 +.. _`#10561`: https://github.com/apache/cloudstack/pull/10561 +.. _`#10563`: https://github.com/apache/cloudstack/pull/10563 +.. _`#10366`: https://github.com/apache/cloudstack/pull/10366 +.. _`#10569`: https://github.com/apache/cloudstack/pull/10569 +.. _`#10562`: https://github.com/apache/cloudstack/pull/10562 +.. _`#10443`: https://github.com/apache/cloudstack/pull/10443 +.. _`#10516`: https://github.com/apache/cloudstack/pull/10516 +.. _`#10515`: https://github.com/apache/cloudstack/pull/10515 +.. _`#10257`: https://github.com/apache/cloudstack/pull/10257 +.. _`#10484`: https://github.com/apache/cloudstack/pull/10484 +.. _`#10472`: https://github.com/apache/cloudstack/pull/10472 +.. _`#10455`: https://github.com/apache/cloudstack/pull/10455 +.. _`#10439`: https://github.com/apache/cloudstack/pull/10439 +.. _`#10466`: https://github.com/apache/cloudstack/pull/10466 +.. _`#10376`: https://github.com/apache/cloudstack/pull/10376 +.. _`#10266`: https://github.com/apache/cloudstack/pull/10266 +.. _`#10351`: https://github.com/apache/cloudstack/pull/10351 +.. _`#10425`: https://github.com/apache/cloudstack/pull/10425 + + +https://github.com/apache/cloudstack/milestone/33?closed=1 + +.. cssclass:: table-striped table-bordered table-hover + + ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| Version | Github | Type | Priority | Description | ++=========================+============+===============+==========+============================================================+ +| 4.19.2.0 | `#10425`_ | | | UI: Fix filtering of templates by account | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10428`_ | | | ipmi: extra log sanitation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10413`_ | | | migrate Vmware to KVM ui issues | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10411`_ | | | VMware Import - Support external VMware VMs in any | +| | | | | folders/subfolders other than the root folder of | +| | | | | datacenter (from KVM hosts) | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10409`_ | | | VMware import issue fix - check and update pools in the | +| | | | | order of disks | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10394`_ | | | UI: Fix `docHelp` links for Add Hosts, Add Clusters, | +| | | | | Disable Clusters and Enable Clusters forms | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10373`_ | | | UI: Fix Apache CloudStack description on the onboarding | +| | | | | page | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10262`_ | | | Fix private gateway acl on static routes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9925`_ | | | Add the option to filter by host when retrieving of | +| | | | | unregistered VMs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10229`_ | | | Support virtio-blk root disk controller | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10357`_ | | | UI: Fixup missing buttons | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10235`_ | | | server: fix scale vm with same disk offering id | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10183`_ | | | cleanup VM IP after expunge in redundant VPC | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9735`_ | | | Fix VMWare leftovers when deleting VM without root disk | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10320`_ | | | List only untagged offerings for Shared networks when tag | +| | | | | isn't passed | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10132`_ | | | Primera pure patches & various small fixes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10317`_ | | | systemvm-registration: update seeded template_store_ref | +| | | | | sizes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10324`_ | | | server: fix pod retrieval during volume attach | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10323`_ | | | Revert test of #10267 | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10280`_ | | | linstor: Fix using multiple primary storage with same | +| | | | | linstor-controller | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10268`_ | | | VPC VR: fix ACL between tier and private gateway | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10126`_ | | | Linstor: encryption support | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10243`_ | | | Hide register template, create/upload volume and create | +| | | | | vpc buttons when zone is not created. | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10216`_ | | | server: fix snapshot physical size | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10255`_ | | | Fix NPE while checking for user data provider | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10222`_ | | | List default network offerings when multiple physical | +| | | | | networks for guest traffic type exists | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10217`_ | | | UI: list backup offerings by zoneid when assign vm to | +| | | | | backup offering | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10237`_ | | | Decrypt zone, cluster, storage details for configuration | +| | | | | values | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10240`_ | | | Improve listing of HA and non-HA hosts when ha.tag setting | +| | | | | is defined and hosts have multiple tags along with ha tag | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10208`_ | | | api,ui: fix empty source cidr value for firewall rule | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10168`_ | | | Allow creation of Shared Networks without IP range if | +| | | | | network offering has no services - specifyvlan = true | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10066`_ | | | Static Routes: fix check on wrong global configuration | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10288`_ | | | ui: fix column filter for templates, isos | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10201`_ | | | Fix volume allocation on local VMFS storage | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10295`_ | | | changed the kubernetestool url | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9941`_ | | | packaging: support both mysql and mariadb on EL8/EL9 | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10245`_ | | | UI: Fix domain view when opening details for a specific | +| | | | | domainid | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10274`_ | | | Fix NPE during account creation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10273`_ | | | Grant access to 2FA APIs for default read-only and support | +| | | | | roles | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10247`_ | | | server: reset 2fa user configuration on incomplete setup | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10234`_ | | | CKS: use --delete-emptydir-data instead of deprecated | +| | | | | --delete-local-data | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10236`_ | | | api/ui: add specifyvlan to network response | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9852`_ | | | list hosts API fix, when any stale entries exists on | +| | | | | storage_pool_host_ref for the removed pools | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10292`_ | | | ui: fix loading for hypervisor filter in serachview | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10279`_ | | | UI: Validate inserted values in numeric global settings | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10267`_ | | | server: fix attach uploaded volume | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10264`_ | | | extra null guard | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10158`_ | | | deal with NPE during host reconnect | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10075`_ | | | cks: prevent npe on cluster listing with removed offering | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10259`_ | | | Handle special characters when exporting ACLs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10215`_ | | | [UI] Switch between allocated and used capacity on | +| | | | | dashboard | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10209`_ | | | Added displaynetwork option in filters for listnetwork | +| | | | | only for admin | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10231`_ | | | Fix local storage deletion cases | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10239`_ | | | ui: fix passing vlan while creating vpc tier | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10218`_ | | | server: Fix host CPU number | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9823`_ | | | kvm: add SCSI controllers based on the number of | +| | | | | virtio-SCSI disks | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9550`_ | | | Fix to allow actions on the network if it belongs to a | +| | | | | project | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10227`_ | | | UI: set redundant state as N/A for non-redundant routers | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10219`_ | | | linstor: Fix ZFS snapshot backup | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10204`_ | | | Fix listing of VMs with removed NICs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10214`_ | | | Configure org.eclipse.jetty.server.Request.maxFormKeys | +| | | | | from server.properties and increase the default value | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10032`_ | | | api: fix access for listSystemVmUsageHistory | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9844`_ | | | Fix NPE issues during host rolling maintenance, due to | +| | | | | host tags and custom constrained/unconstrained service | +| | | | | offering | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10187`_ | | | UI: Fix slider component in global settings with `Range` | +| | | | | type | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10176`_ | | | Clean up network permissions on account deletion | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9644`_ | | | [VMware] Consider CD/DVD drive when calculating next free | +| | | | | unit number for volume attachment over IDE controller | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10174`_ | | | consider a valid ipv4 address as a validish ipv4 /32 cidr | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9900`_ | | | systemvm: fix keystore is reset when patch a systemvm | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10175`_ | | | merge bug fix for #9037; no retrieval of null hosts | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10046`_ | | | upgrade: consider multiple hypervisors and secondary | +| | | | | storages | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9677`_ | | | CheckOnHostCommand: add missing timeout setting | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9725`_ | | | Restrict the migration of volumes attached to VMs in | +| | | | | Starting state | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9764`_ | | | check tags while fetching storage pool for importing vm | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10067`_ | | | VR: fix site-2-site VPN if split connections is enabled | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10065`_ | | | UI: fix cannot open 'Edit tags' modal for static routes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10064`_ | | | VR: apply iptables rules when add/remove static routes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10051`_ | | | Certificate and VM hostname validation improvements | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10040`_ | | | set ulimit for server according to redhat spec | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10093`_ | | | kvm-storage: provide isVMMigrate information to storage | +| | | | | plugins | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10045`_ | | | Allow config drive deletion of migrated VM, on host | +| | | | | maintenance | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10105`_ | | | linstor: improve heartbeat check with also asking linstor | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9173`_ | | | server: simplify role change validation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10086`_ | | | server: fix typo removeaccessvpn in VirtualRouterElement | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10087`_ | | | UI: remove duplicated Instance Name in Public IP details | +| | | | | page | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10047`_ | | | SAML2: add cookie with HttpOnly too | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9744`_ | | | ui: Allow font-awesome icon usage and optimise icon size | +| | | | | inconsistency | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10028`_ | | | Remove SNI option in _run.sh, as it is correct as default. | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10037`_ | | | .github: fix test_certauthority_root in 4.19 | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10035`_ | | | move sql code to the right file | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9999`_ | | | Prevent password updates for SAML and LDAP users | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10033`_ | | | cloudstack-migrate-databases: sql AND added | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#10008`_ | | | Remove user from project before deletion | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9971`_ | | | UI: Tooltip on the host information card to display the | +| | | | | CPU speed in MHz and the memory value in MB (to 3 decimal | +| | | | | places) | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9927`_ | | | UI: Allow accounts of the `User` type to add other | +| | | | | accounts or users to projects through UI | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#7081`_ | | | enable to create VPC portfowarding rules with source cidr | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9759`_ | | | Add new column `last_id` to the table volumes | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9787`_ | | | Allow VMWare import via another host | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9792`_ | | | Linstor: add support for ISO block devices and direct | +| | | | | download | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9949`_ | | | get expunged VM data for job result | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9966`_ | | | UI: Hide section divider when all OAuth providers are | +| | | | | disabled | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9498`_ | | | kvm: ref-count storage pool usage | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9839`_ | | | Revert "storage: fix private templates are not copied to | +| | | | | new image store (#9206)" | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9894`_ | | | Fix listServiceOfferings regression | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9822`_ | | | VR: fix wrong check when compare two configuration files | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9832`_ | | | Linstor: fix live migrate on non-hyperconverged setups | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9222`_ | | | engine-storage: Set SecretConsumerDetail for VM live | +| | | | | migration with storage on shared NFS | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9867`_ | | | Fix Kubernetes cluster view when user is unable to scale | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9856`_ | | | utils: fix invalid JSESSIONID cookie in https setup | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9869`_ | | | kvm: fix ovs network creation issue | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9859`_ | | | linstor/kvm: Workaround a qemu bug and IDE bus discard | +| | | | | enabled. | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9809`_ | | | Fix primary storage update form not showing existing | +| | | | | values | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9770`_ | | | linstor: enable discard for Linstor storage pools | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9756`_ | | | make saml auth request option `forceauthn` configurable | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9798`_ | | | UI: fix unit tests | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9547`_ | | | Filter list VMs by IP address | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#8911`_ | | | Linked clone migration between file-based storages on KVM | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9751`_ | | | API: Fix listing Userdata by keyword or name | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9731`_ | | | Hide UserData field from the EditVM view for VMs that do | +| | | | | not offer it | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9195`_ | | | cleanup validations for VPN connection creation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9739`_ | | | Fix ISO url in test_usage.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#8588`_ | | | CKS: fix creation on shared network if HA is enabled | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9559`_ | | | server: fix nfs version option during mounts | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9374`_ | | | server: apply network ACL even if there is no network ACLs | +| | | | | rules in the ACL list | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9720`_ | | | Revert "list VMs by displayname instead of name" | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9596`_ | | | Fix: Filter out networks without access while getting | +| | | | | networks with SG with free IPs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9711`_ | | | ui: load project list with minimum details | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9006`_ | | | build/packaging: build tungsten plugin only if noredist is | +| | | | | passed | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9637`_ | | | Fixed Unable to create a domain when networkdomain is | +| | | | | mentioned and cleared | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#8846`_ | | | Removed deprecated instruction MAINTAINER | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9636`_ | | | [VMware] Make disk controller selection on volume | +| | | | | attachment consistent with VM creation and start | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9698`_ | | | lb: fix haproxy cannot start if algorithm is not lowercase | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9700`_ | | | UI: enable project menu on mobile devices | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9563`_ | | | Fix resource count discrepancy while associating IP | +| | | | | address to a network | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9200`_ | | | refactor: cloud-sysvmadm script | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9557`_ | | | UI: Fix VPC network offerings listing on VPC tier creation | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#8503`_ | | | list VMs by displayname instead of name | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9669`_ | | | CPVM: move focus on input area after clearing clipboard | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9461`_ | | | Restore listNetworks behavior & clean up the code | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9652`_ | | | UI: Fix starting VMs through group action by | +| | | | | non-root-admin users | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9528`_ | | | Linstor: Fix migrate primary storage | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9428`_ | | | Fix root disk resize issue when service offering has no | +| | | | | root disk size specified | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9624`_ | | | propagate sort order through retrieval sequence | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9634`_ | | | UI: list vms with details=min when attach a volume to vm | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9632`_ | | | linstor: update java-linstor dependency to 0.5.2 | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9239`_ | | | Fix snapshot deletion on template creation failure | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9206`_ | | | storage: fix private templates are not copied to new image | +| | | | | store | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9567`_ | | | Add validation for secstorage.allowed.internal.sites | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9568`_ | | | VR: remove vpn user info when apply vpn users list | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9578`_ | | | server: fix stopped vm volume migration check on local | +| | | | | volume attach | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9588`_ | | | Updated listStoragePools response - added new managed | +| | | | | parameter | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9560`_ | | | linstor: set/unset allow-two-primaries and protocol on rc | +| | | | | level | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9573`_ | | | Fix VGPU available devices listing | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9554`_ | | | ui: show guest networks for guest vlans list | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9575`_ | | | Fix userdata append header restrictions | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9255`_ | | | Add certificate validation to check headers | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9572`_ | | | Update project account for all the events with project | +| | | | | account owner, except for create project event | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9468`_ | | | [VMware] Disconnect/Detach config drive ISO (if exists) on | +| | | | | stop VM | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9433`_ | | | [VMware] Update data disk controller same as the root disk | +| | | | | controller type when it is not set in the VM detail | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9589`_ | | | [UI] Add project toggle for buckets | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9459`_ | | | Fix usage volume size after resizing | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9540`_ | | | Added domain path to all entities | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9571`_ | | | test: fix component tests test_acl_isolatednetwork and | +| | | | | test_acl_isolatednetwork_delete | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9422`_ | | | allow users to apply extraconfig on updating VMs | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9545`_ | | | Fix Template and ISO upload events | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9417`_ | | | linstor: Improve copyPhysicalDisk performance | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9385`_ | | | add procedures procedure | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9201`_ | | | Ensure affinity groups are honored when VMs are deployed | +| | | | | in parallel | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9499`_ | | | test: fix component test | +| | | | | test_acl_sharednetwork_deployVM-impersonation.py | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9390`_ | | | libvirtstorageadaptor: better handle failed libvirt | +| | | | | storagepool destroy | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9447`_ | | | Fix snapshot chain being deleted on XenServer | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9419`_ | | | API: Fix missing keys in listZonesMetrics response | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9399`_ | | | ui: vm metrics note about behaviour across hypervisors | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9434`_ | | | Fixup CKS UI for external managed clusters | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9458`_ | | | UI: Display Firewall, LB and Port Forwading rules tab for | +| | | | | CKS clusters deployed on isolated networks | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9442`_ | | | Fix removal of usage records | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#9437`_ | | | Add systemvmtemplate arm64 build support | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ +| 4.19.2.0 | `#8833`_ | | | Fix link to removed volumes being shown in info card and | +| | | | | list view | ++-------------------------+------------+---------------+----------+------------------------------------------------------------+ + +179 Issues listed + +.. _`#10425`: https://github.com/apache/cloudstack/pull/10425 +.. _`#10428`: https://github.com/apache/cloudstack/pull/10428 +.. _`#10413`: https://github.com/apache/cloudstack/pull/10413 +.. _`#10411`: https://github.com/apache/cloudstack/pull/10411 +.. _`#10409`: https://github.com/apache/cloudstack/pull/10409 +.. _`#10394`: https://github.com/apache/cloudstack/pull/10394 +.. _`#10373`: https://github.com/apache/cloudstack/pull/10373 +.. _`#10262`: https://github.com/apache/cloudstack/pull/10262 +.. _`#9925`: https://github.com/apache/cloudstack/pull/9925 +.. _`#10229`: https://github.com/apache/cloudstack/pull/10229 +.. _`#10357`: https://github.com/apache/cloudstack/pull/10357 +.. _`#10235`: https://github.com/apache/cloudstack/pull/10235 +.. _`#10183`: https://github.com/apache/cloudstack/pull/10183 +.. _`#9735`: https://github.com/apache/cloudstack/pull/9735 +.. _`#10320`: https://github.com/apache/cloudstack/pull/10320 +.. _`#10132`: https://github.com/apache/cloudstack/pull/10132 +.. _`#10317`: https://github.com/apache/cloudstack/pull/10317 +.. _`#10324`: https://github.com/apache/cloudstack/pull/10324 +.. _`#10323`: https://github.com/apache/cloudstack/pull/10323 +.. _`#10280`: https://github.com/apache/cloudstack/pull/10280 +.. _`#10268`: https://github.com/apache/cloudstack/pull/10268 +.. _`#10126`: https://github.com/apache/cloudstack/pull/10126 +.. _`#10243`: https://github.com/apache/cloudstack/pull/10243 +.. _`#10216`: https://github.com/apache/cloudstack/pull/10216 +.. _`#10255`: https://github.com/apache/cloudstack/pull/10255 +.. _`#10222`: https://github.com/apache/cloudstack/pull/10222 +.. _`#10217`: https://github.com/apache/cloudstack/pull/10217 +.. _`#10237`: https://github.com/apache/cloudstack/pull/10237 +.. _`#10240`: https://github.com/apache/cloudstack/pull/10240 +.. _`#10208`: https://github.com/apache/cloudstack/pull/10208 +.. _`#10168`: https://github.com/apache/cloudstack/pull/10168 +.. _`#10066`: https://github.com/apache/cloudstack/pull/10066 +.. _`#10288`: https://github.com/apache/cloudstack/pull/10288 +.. _`#10201`: https://github.com/apache/cloudstack/pull/10201 +.. _`#10295`: https://github.com/apache/cloudstack/pull/10295 +.. _`#9941`: https://github.com/apache/cloudstack/pull/9941 +.. _`#10245`: https://github.com/apache/cloudstack/pull/10245 +.. _`#10274`: https://github.com/apache/cloudstack/pull/10274 +.. _`#10273`: https://github.com/apache/cloudstack/pull/10273 +.. _`#10247`: https://github.com/apache/cloudstack/pull/10247 +.. _`#10234`: https://github.com/apache/cloudstack/pull/10234 +.. _`#10236`: https://github.com/apache/cloudstack/pull/10236 +.. _`#9852`: https://github.com/apache/cloudstack/pull/9852 +.. _`#10292`: https://github.com/apache/cloudstack/pull/10292 +.. _`#10279`: https://github.com/apache/cloudstack/pull/10279 +.. _`#10267`: https://github.com/apache/cloudstack/pull/10267 +.. _`#10264`: https://github.com/apache/cloudstack/pull/10264 +.. _`#10158`: https://github.com/apache/cloudstack/pull/10158 +.. _`#10075`: https://github.com/apache/cloudstack/pull/10075 +.. _`#10259`: https://github.com/apache/cloudstack/pull/10259 +.. _`#10215`: https://github.com/apache/cloudstack/pull/10215 +.. _`#10209`: https://github.com/apache/cloudstack/pull/10209 +.. _`#10231`: https://github.com/apache/cloudstack/pull/10231 +.. _`#10239`: https://github.com/apache/cloudstack/pull/10239 +.. _`#10218`: https://github.com/apache/cloudstack/pull/10218 +.. _`#9823`: https://github.com/apache/cloudstack/pull/9823 +.. _`#9550`: https://github.com/apache/cloudstack/pull/9550 +.. _`#10227`: https://github.com/apache/cloudstack/pull/10227 +.. _`#10219`: https://github.com/apache/cloudstack/pull/10219 +.. _`#10204`: https://github.com/apache/cloudstack/pull/10204 +.. _`#10214`: https://github.com/apache/cloudstack/pull/10214 +.. _`#10032`: https://github.com/apache/cloudstack/pull/10032 +.. _`#9844`: https://github.com/apache/cloudstack/pull/9844 +.. _`#10187`: https://github.com/apache/cloudstack/pull/10187 +.. _`#10176`: https://github.com/apache/cloudstack/pull/10176 +.. _`#9644`: https://github.com/apache/cloudstack/pull/9644 +.. _`#10174`: https://github.com/apache/cloudstack/pull/10174 +.. _`#9900`: https://github.com/apache/cloudstack/pull/9900 +.. _`#10175`: https://github.com/apache/cloudstack/pull/10175 +.. _`#10046`: https://github.com/apache/cloudstack/pull/10046 +.. _`#9677`: https://github.com/apache/cloudstack/pull/9677 +.. _`#9725`: https://github.com/apache/cloudstack/pull/9725 +.. _`#9764`: https://github.com/apache/cloudstack/pull/9764 +.. _`#10067`: https://github.com/apache/cloudstack/pull/10067 +.. _`#10065`: https://github.com/apache/cloudstack/pull/10065 +.. _`#10064`: https://github.com/apache/cloudstack/pull/10064 +.. _`#10051`: https://github.com/apache/cloudstack/pull/10051 +.. _`#10040`: https://github.com/apache/cloudstack/pull/10040 +.. _`#10093`: https://github.com/apache/cloudstack/pull/10093 +.. _`#10045`: https://github.com/apache/cloudstack/pull/10045 +.. _`#10105`: https://github.com/apache/cloudstack/pull/10105 +.. _`#9173`: https://github.com/apache/cloudstack/pull/9173 +.. _`#10086`: https://github.com/apache/cloudstack/pull/10086 +.. _`#10087`: https://github.com/apache/cloudstack/pull/10087 +.. _`#10047`: https://github.com/apache/cloudstack/pull/10047 +.. _`#9744`: https://github.com/apache/cloudstack/pull/9744 +.. _`#10028`: https://github.com/apache/cloudstack/pull/10028 +.. _`#10037`: https://github.com/apache/cloudstack/pull/10037 +.. _`#10035`: https://github.com/apache/cloudstack/pull/10035 +.. _`#9999`: https://github.com/apache/cloudstack/pull/9999 +.. _`#10033`: https://github.com/apache/cloudstack/pull/10033 +.. _`#10008`: https://github.com/apache/cloudstack/pull/10008 +.. _`#9971`: https://github.com/apache/cloudstack/pull/9971 +.. _`#9927`: https://github.com/apache/cloudstack/pull/9927 +.. _`#7081`: https://github.com/apache/cloudstack/pull/7081 +.. _`#9759`: https://github.com/apache/cloudstack/pull/9759 +.. _`#9787`: https://github.com/apache/cloudstack/pull/9787 +.. _`#9792`: https://github.com/apache/cloudstack/pull/9792 +.. _`#9949`: https://github.com/apache/cloudstack/pull/9949 +.. _`#9966`: https://github.com/apache/cloudstack/pull/9966 +.. _`#9498`: https://github.com/apache/cloudstack/pull/9498 +.. _`#9839`: https://github.com/apache/cloudstack/pull/9839 +.. _`#9894`: https://github.com/apache/cloudstack/pull/9894 +.. _`#9822`: https://github.com/apache/cloudstack/pull/9822 +.. _`#9832`: https://github.com/apache/cloudstack/pull/9832 +.. _`#9222`: https://github.com/apache/cloudstack/pull/9222 +.. _`#9867`: https://github.com/apache/cloudstack/pull/9867 +.. _`#9856`: https://github.com/apache/cloudstack/pull/9856 +.. _`#9869`: https://github.com/apache/cloudstack/pull/9869 +.. _`#9859`: https://github.com/apache/cloudstack/pull/9859 +.. _`#9809`: https://github.com/apache/cloudstack/pull/9809 +.. _`#9770`: https://github.com/apache/cloudstack/pull/9770 +.. _`#9756`: https://github.com/apache/cloudstack/pull/9756 +.. _`#9798`: https://github.com/apache/cloudstack/pull/9798 +.. _`#9547`: https://github.com/apache/cloudstack/pull/9547 +.. _`#8911`: https://github.com/apache/cloudstack/pull/8911 +.. _`#9751`: https://github.com/apache/cloudstack/pull/9751 +.. _`#9731`: https://github.com/apache/cloudstack/pull/9731 +.. _`#9195`: https://github.com/apache/cloudstack/pull/9195 +.. _`#9739`: https://github.com/apache/cloudstack/pull/9739 +.. _`#8588`: https://github.com/apache/cloudstack/pull/8588 +.. _`#9559`: https://github.com/apache/cloudstack/pull/9559 +.. _`#9374`: https://github.com/apache/cloudstack/pull/9374 +.. _`#9720`: https://github.com/apache/cloudstack/pull/9720 +.. _`#9596`: https://github.com/apache/cloudstack/pull/9596 +.. _`#9711`: https://github.com/apache/cloudstack/pull/9711 +.. _`#9006`: https://github.com/apache/cloudstack/pull/9006 +.. _`#9637`: https://github.com/apache/cloudstack/pull/9637 +.. _`#8846`: https://github.com/apache/cloudstack/pull/8846 +.. _`#9636`: https://github.com/apache/cloudstack/pull/9636 +.. _`#9698`: https://github.com/apache/cloudstack/pull/9698 +.. _`#9700`: https://github.com/apache/cloudstack/pull/9700 +.. _`#9563`: https://github.com/apache/cloudstack/pull/9563 +.. _`#9200`: https://github.com/apache/cloudstack/pull/9200 +.. _`#9557`: https://github.com/apache/cloudstack/pull/9557 +.. _`#8503`: https://github.com/apache/cloudstack/pull/8503 +.. _`#9669`: https://github.com/apache/cloudstack/pull/9669 +.. _`#9461`: https://github.com/apache/cloudstack/pull/9461 +.. _`#9652`: https://github.com/apache/cloudstack/pull/9652 +.. _`#9528`: https://github.com/apache/cloudstack/pull/9528 +.. _`#9428`: https://github.com/apache/cloudstack/pull/9428 +.. _`#9624`: https://github.com/apache/cloudstack/pull/9624 +.. _`#9634`: https://github.com/apache/cloudstack/pull/9634 +.. _`#9632`: https://github.com/apache/cloudstack/pull/9632 +.. _`#9239`: https://github.com/apache/cloudstack/pull/9239 +.. _`#9206`: https://github.com/apache/cloudstack/pull/9206 +.. _`#9567`: https://github.com/apache/cloudstack/pull/9567 +.. _`#9568`: https://github.com/apache/cloudstack/pull/9568 +.. _`#9578`: https://github.com/apache/cloudstack/pull/9578 +.. _`#9588`: https://github.com/apache/cloudstack/pull/9588 +.. _`#9560`: https://github.com/apache/cloudstack/pull/9560 +.. _`#9573`: https://github.com/apache/cloudstack/pull/9573 +.. _`#9554`: https://github.com/apache/cloudstack/pull/9554 +.. _`#9575`: https://github.com/apache/cloudstack/pull/9575 +.. _`#9255`: https://github.com/apache/cloudstack/pull/9255 +.. _`#9572`: https://github.com/apache/cloudstack/pull/9572 +.. _`#9468`: https://github.com/apache/cloudstack/pull/9468 +.. _`#9433`: https://github.com/apache/cloudstack/pull/9433 +.. _`#9589`: https://github.com/apache/cloudstack/pull/9589 +.. _`#9459`: https://github.com/apache/cloudstack/pull/9459 +.. _`#9540`: https://github.com/apache/cloudstack/pull/9540 +.. _`#9571`: https://github.com/apache/cloudstack/pull/9571 +.. _`#9422`: https://github.com/apache/cloudstack/pull/9422 +.. _`#9545`: https://github.com/apache/cloudstack/pull/9545 +.. _`#9417`: https://github.com/apache/cloudstack/pull/9417 +.. _`#9385`: https://github.com/apache/cloudstack/pull/9385 +.. _`#9201`: https://github.com/apache/cloudstack/pull/9201 +.. _`#9499`: https://github.com/apache/cloudstack/pull/9499 +.. _`#9390`: https://github.com/apache/cloudstack/pull/9390 +.. _`#9447`: https://github.com/apache/cloudstack/pull/9447 +.. _`#9419`: https://github.com/apache/cloudstack/pull/9419 +.. _`#9399`: https://github.com/apache/cloudstack/pull/9399 +.. _`#9434`: https://github.com/apache/cloudstack/pull/9434 +.. _`#9458`: https://github.com/apache/cloudstack/pull/9458 +.. _`#9442`: https://github.com/apache/cloudstack/pull/9442 +.. _`#9437`: https://github.com/apache/cloudstack/pull/9437 +.. _`#8833`: https://github.com/apache/cloudstack/pull/8833 + + +https://github.com/apache/cloudstack/milestone/31?closed=1 + .. cssclass:: table-striped table-bordered table-hover +-------------------------+----------+------------------------------------------------------------+ | Version | Github | Description | +=========================+==========+============================================================+ -| 4.16.0.0 | `#5665`_ | Revert "parallel nic adding" | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5659`_ | api,server,engine/schema: admin listvm api clusterid | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5661`_ | linstor-volume-plugin: Only create diskless assignments on | -| | | nodes | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5645`_ | Marvin: change some vlans in test_data.py | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5657`_ | engine/schema: fix build error in #5642 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5642`_ | upgrade/systemvm: add template zone entries | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5646`_ | usage: updateNewMaxId after sanity check | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5629`_ | cks: refactor code to be architecture agnostic | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5644`_ | ui: fix jobid param for migrate VM storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5638`_ | UI - Show password after reinstalling VM | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5643`_ | UI: ip6gateway is missing in createNetwork API | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5624`_ | core: use the URL scheme same as iframe for non-SSL | -| | | enabled consoles | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5586`_ | Check the pool used space from the bytes used in the | -| | | storage pool stats collector, for non-default primary | -| | | storage pools that cannot provide stats. | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5621`_ | ui: Fix wrong label for addBrocadeVcsDevice | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5593`_ | [UI] Fixed RBD storage connection bug when there are | -| | | multiple '/', '+' characters in 'RADOS Secret' in Add | -| | | Primary Storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5614`_ | Fix duplicate provider field when adding primary storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5612`_ | ui: Removing double footer in NSP forms | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5608`_ | UI - Fixes incorrect switching between pages on Port | -| | | Forwarding & Load Balancing | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5609`_ | ui: Prevent multiple VM selection and list only VMs IP | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5607`_ | UI - Fixes the error of not being able to search for | -| | | osType selection | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5599`_ | UI - Sort list idps by alphabest | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5597`_ | UI - Hidden features checkbox as user role | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5598`_ | Fix systemVM template name in metadata file | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5601`_ | ui: Prevent users from viewing - Project Configure Limit | -| | | tab | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5585`_ | Fixing error in kube smoke tests | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5583`_ | vmware: fix NPE for volume migration CLUSTER to ZONE-wide | -| | | pool (#5582) | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5580`_ | VPC: support LB in multiple vpc tiers if LB provider is | -| | | VpcVirtualRouter | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5582`_ | vmware: fix NPE for volume migration CLUSTER to ZONE-wide | -| | | pool | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5575`_ | Fix storage cleanup corner case preventing VM deletion | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5577`_ | UI - Fix the error of not being able to read the length of | -| | | numeric | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5573`_ | api: Fix response object for various APIs | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5574`_ | CKS: use cluster-autoscaler-standard.yaml in kubernetes | -| | | repo | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5571`_ | api: Fix RestartNetwork response type | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5565`_ | engine/schema: add unique constraint for sshkeys UUID | -| | | column | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5572`_ | UI: Restrict viewing project invitation options when | -| | | configuration is disabled | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5569`_ | UI - Fix display IP Address allow input | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5568`_ | Fix warning caused due to duplicate declaration of plugin | -| | | - pom.xml | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5561`_ | [KVM] Add the source disk format for disk conversion/copy | -| | | using 'qemu-img convert', when specified explicitly, for | -| | | ScaleIO | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5560`_ | Updated storage type of the volume, in the volume | -| | | response, based on the underlying storage pool | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5557`_ | Use deploy as is for Vmware tests | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5410`_ | CloudStack fails to migrate VM with volume when there are | -| | | datadisks attatched | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5554`_ | VR: skip dhcp/dns health check in some cases | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5543`_ | xcp-ng: fix vm boot options | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4329`_ | Adding AutoScaling for cks + CKS CoreOS EOL update + | -| | | systemvmtemplate improvements | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5551`_ | Add empty config value for scope based config setting | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5542`_ | Report the PowerFlex/ScaleIO disk copy failure during | -| | | volume migration and fail the migration | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5540`_ | kvm available memory calculation optimization | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5539`_ | Fix resize volume and migrate volume to update volume path | -| | | if DRS is applied on volume in datastore cluster | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5471`_ | vmware, network: add maclearning option | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5547`_ | an inject annotation short | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5541`_ | parallel nic adding | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5546`_ | [UI] Edit backup offering | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5530`_ | VR: fix data-server if shared network has multiple ip | -| | | ranges | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5513`_ | kvm: add VM Settings for virtual GPU hardware type and | -| | | memory | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5501`_ | server: check service offering (storage) tags when | -| | | reallocate a ROOT disk | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5532`_ | Remove logic that creates gap for multiple 'source NAT' in | -| | | VR | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5446`_ | OVS/GRE: bug fixes | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5470`_ | vmware, ui: update portgroup on network update | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5511`_ | Create UpdateBackupOffering API | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5510`_ | Fix export snapshot and template to secondary storage to | -| | | export only required disk | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5504`_ | Fix permission issue during Diagnostic service garbage | -| | | collection | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5537`_ | UI - Remove duplicate endipv6 item in shared network | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5526`_ | UI - Fixes modal width by device screen | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5521`_ | server: cannot deploy/start vm if service offering has | -| | | multiple tags | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4215`_ | Enable account settings to be visible under domain | -| | | settings | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5522`_ | Datastore cluster protocol in zone wizard for vmware | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5515`_ | simulator: Add support to scale a VM | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4826`_ | Allow storage plugins to get storage/volume stats without | -| | | sending commands to hosts | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5520`_ | Allow users (User account Role) to delete / archive events | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5469`_ | server: add vm boot details for start vm api | +| 4.20.0.0 | `#8911`_ | Linked clone migration between file-based storages on KVM | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4617`_ | Provide option to force delete the project | +| 4.20.0.0 | `#9751`_ | API: Fix listing Userdata by keyword or name | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5503`_ | test_vpc_redundant.py: reduce sleep time from 1 hour to 21 | -| | | mins | +| 4.20.0.0 | `#9731`_ | Hide UserData field from the EditVM view for VMs that do | +| | | not offer it | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5455`_ | Improve Veeam Plugin logs | +| 4.20.0.0 | `#9195`_ | cleanup validations for VPN connection creation | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5507`_ | tools/docker: Upgrade to ubuntu 20.04 , MySQL 8 and | -| | | python3 | +| 4.20.0.0 | `#9738`_ | debian12: update debian/control | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5505`_ | marvin: Refactor - cleanup of resource after test run | +| 4.20.0.0 | `#9723`_ | Shutdown expunged resources cleanup executor properly, and | +| | | allow other components to configure/start/stop on error | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5428`_ | resource limit: Fix resource limit check on VM start | +| 4.20.0.0 | `#9739`_ | Fix ISO url in test_usage.py | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5483`_ | marvin: Fix intermittent failure observed in | -| | | test_02_list_snapshots_with_removed_data_store | +| 4.20.0.0 | `#7650`_ | CKS: add ConfigDrive to cloud-init datasource_list in | +| | | systemvm template | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5419`_ | CPVM: use X509ExtendedTrustManager to skip hostname | -| | | verification | +| 4.20.0.0 | `#8588`_ | CKS: fix creation on shared network if HA is enabled | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5480`_ | Refactor GroupByExtension to improve test logic | +| 4.20.0.0 | `#9664`_ | PowerFlex on demand disable config key | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5490`_ | UI: Fix VM state column | +| 4.20.0.0 | `#9559`_ | server: fix nfs version option during mounts | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#3804`_ | Display capability info in listNetwork response | +| 4.20.0.0 | `#9374`_ | server: apply network ACL even if there is no network ACLs | +| | | rules in the ACL list | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5496`_ | ui: recommend adv zone to new users and show basic zone as | -| | | bottom option | +| 4.20.0.0 | `#9720`_ | Revert "list VMs by displayname instead of name" | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5495`_ | move broken unmaintained test out of ".../smoke" | +| 4.20.0.0 | `#9596`_ | Fix: Filter out networks without access while getting | +| | | networks with SG with free IPs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5492`_ | Update README.md | +| 4.20.0.0 | `#9711`_ | ui: load project list with minimum details | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5486`_ | travis: fix test/integration/component/test_public_ip.py | +| 4.20.0.0 | `#9006`_ | build/packaging: build tungsten plugin only if noredist is | +| | | passed | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5488`_ | ui: Add support to filter role permissions | +| 4.20.0.0 | `#9637`_ | Fixed Unable to create a domain when networkdomain is | +| | | mentioned and cleared | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5481`_ | ui: fix create account/user with saml | +| 4.20.0.0 | `#8846`_ | Removed deprecated instruction MAINTAINER | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5485`_ | ui: Fix editVM in projectview | +| 4.20.0.0 | `#9714`_ | Fix main build errors | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5454`_ | [UI] Fixes: edit tariff quota and allow user driven | -| | | backups parameter in Import Backup Offering | +| 4.20.0.0 | `#9636`_ | [VMware] Make disk controller selection on volume | +| | | attachment consistent with VM creation and start | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4890`_ | Universal sshkey and password manager script | +| 4.20.0.0 | `#9699`_ | VR: fix password server exception when no password is | +| | | found | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5458`_ | New API endpoint to update pod management network IP range | +| 4.20.0.0 | `#9698`_ | lb: fix haproxy cannot start if algorithm is not lowercase | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5472`_ | UI - Fixes search error in selectbox | +| 4.20.0.0 | `#9700`_ | UI: enable project menu on mobile devices | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5468`_ | api: Fix list templates when no secondary stores present | +| 4.20.0.0 | `#9563`_ | Fix resource count discrepancy while associating IP | +| | | address to a network | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5474`_ | change logging during upgrade | +| 4.20.0.0 | `#9676`_ | Enable Backup and Recovery for Shared Filesystems | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5459`_ | server: Add support to encrypt https.keystore.password in | -| | | server.properties | +| 4.20.0.0 | `#9200`_ | refactor: cloud-sysvmadm script | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5476`_ | UI: Fixes issue during logout as user / domain admin | +| 4.20.0.0 | `#9557`_ | UI: Fix VPC network offerings listing on VPC tier creation | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5411`_ | Add New API endpoint: UpdateVlanIpRange | +| 4.20.0.0 | `#8503`_ | list VMs by displayname instead of name | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5464`_ | server: fix list public ip returns duplicated records | +| 4.20.0.0 | `#9696`_ | pre-commit run --all-files; fix end of file | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4634`_ | Display vlan ip range for specified domainid | +| 4.20.0.0 | `#9680`_ | Update of the schema 41910to42000.sql for compatibility | +| | | with MariaDB version 10.3.38. | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5465`_ | ui: Move resource icon to first column for VM list view | +| 4.20.0.0 | `#9655`_ | Fix toc generation for api docs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5449`_ | [Vmware] Add missing condition to cleanup nics if there | -| | | are commands to send | +| 4.20.0.0 | `#9681`_ | Implemented the lateral expansion of the area-box in the | +| | | forms (creat… | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5463`_ | UI: list static routes with listall=true | +| 4.20.0.0 | `#9669`_ | CPVM: move focus on input area after clearing clipboard | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5460`_ | Display ACL id for the private gateway | +| 4.20.0.0 | `#9661`_ | List Events returns intermittent SQL exception.Fixed | +| | | listEvents intermittent exception. | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5453`_ | Updated the event message with proper json format for cmd | -| | | info and job result | +| 4.20.0.0 | `#9675`_ | Minor naming changes in Shared FileSystems 4.20 Feature | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5369`_ | kvm: Add check if host meets the minimum requirements | +| 4.20.0.0 | `#9663`_ | Provide encryption key for DATA volume type (in addition | +| | | to ROOT) to copy volume. | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5420`_ | server: allow listing custom offerings for a running VM | +| 4.20.0.0 | `#9585`_ | allow domain suffix update in shared networks | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5448`_ | [Vmware] Fix for ovf templates with prefix | +| 4.20.0.0 | `#9662`_ | Host capacity calculation: use VM creation time if update | +| | | time is null. | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5456`_ | move out broken tests | +| 4.20.0.0 | `#9509`_ | Feature: Forgot password | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4994`_ | Linstor volume plugin | +| 4.20.0.0 | `#9656`_ | Fix the Cloudian Integration SSO Redirect link | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4635`_ | Persist vpn connection state before restarting | +| 4.20.0.0 | `#9188`_ | Enhance the `listAffinityGroups` API by adding the | +| | | dedicated resources related to an affinity group | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5388`_ | kvm: honor migrate.wait and abort vm migration job | +| 4.20.0.0 | `#9566`_ | Allow more generic searches of ACLs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5451`_ | ui: Fix Load Balancer Rules alignment issue | +| 4.20.0.0 | `#8924`_ | Add logs to CPVM connection process | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5424`_ | Updated pod response, grouped the parameters: "startip, | -| | | endip, vlanid, forsystemvms" as ip range response and | -| | | added to ipranges parameter. | +| 4.20.0.0 | `#9461`_ | Restore listNetworks behavior & clean up the code | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5447`_ | ui: Refresh Usage dashboard when swapping between Project | -| | | and Default view | +| 4.20.0.0 | `#9633`_ | Feature: Allow adding delete protection for VMs & volumes | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5157`_ | UI: Support to upload resource icons | +| 4.20.0.0 | `#9652`_ | UI: Fix starting VMs through group action by | +| | | non-root-admin users | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5425`_ | api: Update DNS on changing VM name | +| 4.20.0.0 | `#9528`_ | Linstor: Fix migrate primary storage | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4741`_ | VM has wrong network statistics with multiple nics in | -| | | shared networks | +| 4.20.0.0 | `#8906`_ | NSX Integration fixes | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5450`_ | UI - Remove white space after detail string in Firefox | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5417`_ | server: skip max guest limit check for KVM host | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5421`_ | server: fix addCluster for vmware, others | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5439`_ | ui: Fix Scale VM failure - missing args when custom | -| | | compute offering is selected | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5423`_ | ui: select newly created network in deploy vm | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5395`_ | ui: Allow searching in dropdowns | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5441`_ | utils: remove duplicate commons-lang3 dependency | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5438`_ | ui: Send deployvm api call as post | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5437`_ | ui: Remove double footer | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5435`_ | Fix public IP actions buttons not working unless | -| | | refreshing the page | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5432`_ | api, ui: return default ui pagesize as part of capability | -| | | response | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5427`_ | ui: fix add management ip range form | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5431`_ | Hide settings button if not on development mode | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5429`_ | ui: show nicAdapter selection for VMware non-readfromova | -| | | template | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5398`_ | Prevent double counting storage pools | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5358`_ | Fix potential NullPointerException in findStoragePool | -| | | (VolumeOrchestrator) | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5416`_ | travis: Fix failing test due to change in test name | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5067`_ | Keep volume policies after migrating it to another primary | -| | | storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#3975`_ | Issue #3974 Deploying mysql-ha jar file into its own | -| | | path... | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5103`_ | Extend the Annotations framework | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5401`_ | marvin: fix exception logging | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5396`_ | cleanup: kvm-storage - fix misleading error log | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5390`_ | server: fix reset sshkey is broken in master/4.16 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4534`_ | Migrate vm across clusters | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5402`_ | UI: Add router links to notifications and show error | -| | | description | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5387`_ | api, ui: fix NPE with deployVirtualMachine when null | -| | | boottype | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5408`_ | Legacy UI: Display Accounts Tab to Project Admins | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5066`_ | CLOUDSTACK-10436:remind users to use correct permission | -| | | for tmp dir and fixed an NPE | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5404`_ | Allow public templates with no url to be migrated | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5394`_ | ui: Honour default.ui.page.size | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5259`_ | usage: create backup usage record for vmId-offeringId pair | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5307`_ | Filter disk / service offerings by domain at DB level | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5339`_ | server: check server capacity when start/deploy a vm | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5333`_ | vmware: delete snapshot disk after backup to secondary | -| | | storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5403`_ | Add 4.15.2 schema and upgrade path | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5082`_ | component test ports/fixes in python3 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5399`_ | travis: fix consistent failures noticed on few tests | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5376`_ | Use source IP from same subnet for snat | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5375`_ | vr: ipsec/l2tp vpn secret with no ID selectors | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5374`_ | [VMware] Cancel the pending tasks for a worker VM before | -| | | destroying it | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5379`_ | api: List details of template download state for stores | -| | | corresponding to a zone | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5380`_ | vmware: check checksum before copying systemvm ISO to | -| | | decide if it is needed | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5392`_ | UI - Scale VM - Fix compute offering selection not working | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4852`_ | Allow host cert renewals even if client auth strictness is | -| | | false | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5393`_ | ui: Refresh page on deployvm result | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5373`_ | server: do not remove volume from DB if fail to expunge it | -| | | from primary storage or secondary storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5335`_ | xcp-ng: allow passing vm boot options | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5349`_ | Fix of creating volumes from snapshots without backup to | -| | | secondary storage | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5366`_ | updated maven dependency due to #5363 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5385`_ | engine/schema: Use same upgrade path as 4.15.1-4.16.0 as | -| | | for 4.15.2 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5371`_ | server: improve attach volume in specific cases | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5311`_ | [VMware] Start VM with deploy-as-is template having | -| | | multiple controller types | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5377`_ | [VMware] Added Worker VM tags for few cloned VMs while | -| | | performing some volume operations. | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5368`_ | ui: Fix action bar in place | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5364`_ | server: allow destroy/recover volumes which are attached | -| | | to removed vms | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4701`_ | Added support for removing unused port groups on VMWare | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5384`_ | ubuntu: Fix failure to scp diagnostic data file from SSVM | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5356`_ | server: detach data disks before destroying vms | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#1257`_ | [VMware DRS] Adding new host to DRS cluster does not | -| | | participate in load balancing. | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5367`_ | ui: Fix search with same parameters | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5360`_ | ui: Go back for delete actions before querying async job | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5357`_ | Externalize VMWare stats time window config | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4570`_ | Externalize KVM Agent's option to change migration thread | -| | | timeout | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5187`_ | Added ability to create schemas only when using | -| | | cloudstack-setup-data… | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5319`_ | vr: reload dnsmasq when start vms | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5351`_ | Externalize vm stats increment in memory | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4662`_ | Feat/ram reservation | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5354`_ | Fix security_groups for c8/suse | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5359`_ | UI - Add storage name to delete primary/secondary storage | -| | | dialog | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5337`_ | Bypass empty string check for username and password | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5345`_ | UI - VM - hide button take vm volume snapshot for | -| | | Destroyed state | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5341`_ | remove doubles before save | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5355`_ | ui: Support to view template download progress across all | -| | | stores | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4586`_ | Externalize kvm agent storage reboot configuration | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4878`_ | Support vm dynamic scaling with kvm | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5321`_ | Remove storage scope validation on KVM live migration | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5194`_ | adapt condition to use the correct letter for pvlan types | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5331`_ | vr: cleanup files in /var/cache/cloud/processed every day | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5348`_ | security group: fix component test | -| | | test_multiple_nic_support.py failures | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5328`_ | Fix iptable rules when chain reference count is 0 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5346`_ | test: Fix travis failure - test_outofbandmanagement.py | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4618`_ | Allow users to update volume name | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5342`_ | add license header in HostMetricsResponseTest.java | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5326`_ | ui: Update placeholders for adding new tier | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5110`_ | Adding SUSE 15 support | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5318`_ | Fix iptable rules in ubuntu 20 for bridge name | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5217`_ | Possiblity to choose between docker and podman from the | -| | | command line | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5329`_ | metrics: fix hostsmetricsresponse for zero cpu, locale | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5303`_ | UI - Zone wizard - Fixes wrong add resource step with | -| | | localstorageenabled | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5320`_ | server: use id column as secondary sort criteria with | -| | | sortKey | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5327`_ | s2svpn: Set initial state as Connecting | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5317`_ | systemvmtemplate: bump to Debian 11.0.0 systemvmtemplate | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5158`_ | Adding support for RHEL8 binary-compatible variants | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5323`_ | UI - systemVM - Fix error message `jobid` not found when | -| | | moving to another host | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5325`_ | ui (importUnmanagedInstance) : Show project list to which | -| | | the instance is to be imported | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4776`_ | Add sent and received bytes to listNetworks and | -| | | listVirtualMachines. | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4780`_ | Add SharedMountPoint to KVMs supported storage pool types | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4399`_ | PR multi tags in compute offering [#4398] | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5312`_ | Add missing command - syncStoragePool in main branch | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5304`_ | compatibility fix for Packer v1.7.4, update debian | -| | | template to 10.10.0 | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5273`_ | Externalize config to enable manually setting CPU topology | -| | | on KVM VM | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5258`_ | vmware: get recommended disk controller only when root or | -| | | data disk controller is osdefault | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5274`_ | db: make *_details.value non-nullable | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5242`_ | Add internal cs name to vm during the ingest | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4630`_ | disable hot add memory and cpu via vm settings | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5305`_ | Add missing labels and sort them | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4699`_ | Add new registers in guest_os | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5249`_ | Global setting to select preferred storage pool | -+-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5052`_ | UI: Dark mode toggle button on Management Server | +| 4.20.0.0 | `#9107`_ | Refactor type and range validation in configuration update | +| | | process | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5301`_ | ui: fix display host hypervisorversion | +| 4.20.0.0 | `#8511`_ | Add logs to `LibvirtComputingResource`'s metrics | +| | | collection process | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5289`_ | test/vmware: add live migratevmwithvolume test and fix | +| 4.20.0.0 | `#9639`_ | ui: refactor config update/reset notification | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4885`_ | UI: Add multiple management server support | +| 4.20.0.0 | `#9619`_ | New Feature: Multi-arch Zones | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5298`_ | UI - Fixes - Ctrl+Enter events error | +| 4.20.0.0 | `#9647`_ | engine/schema: update url links to match new | +| | | systemvmtemplate names | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5299`_ | ui: Fix sending false for isdynamicallyscalable, haenable | -| | | in EditVM | +| 4.20.0.0 | `#9428`_ | Fix root disk resize issue when service offering has no | +| | | root disk size specified | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4378`_ | server: Optional destination host when migrate a vm | +| 4.20.0.0 | `#9470`_ | New feature: Dynamic and Static Routing | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5295`_ | ui: Prettify ManageInstances.vue | +| 4.20.0.0 | `#9451`_ | backup: simple NAS backup plugin for KVM | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5254`_ | kubernetes: Deploy kubernetes-provider when creating a | -| | | cluster | +| 4.20.0.0 | `#8389`_ | Add support for Ceph RGW Object Store | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4551`_ | Cleanup volume information from db when deleted | +| 4.20.0.0 | `#9208`_ | Shared Filesystem as a First Class Feature | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4685`_ | Display last updated time for VM | +| 4.20.0.0 | `#9415`_ | Shared Network Firewall (Security groups) in Advanced zone | +| | | without security groups | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4737`_ | Change GET/POST request max length of VM user data to | -| | | 4K/1M | +| 4.20.0.0 | `#9624`_ | propagate sort order through retrieval sequence | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5270`_ | server: skip zone check for PERHOST iso during attachIso | +| 4.20.0.0 | `#8925`_ | Go back to previous timestamp on logging | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5288`_ | Fix migration issue in | -| | | UserVmManagerImpl.migrateVirtualMachineWithVolume | +| 4.20.0.0 | `#9543`_ | Added update, enable, disable events to the | +| | | updateStoragePool API | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5287`_ | UI - Zone Wizard - Fixes the IP range form fields are too | -| | | narrow | +| 4.20.0.0 | `#9569`_ | Global setting to allow/disallow users to force stop a vm | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5282`_ | Fix regression on create volume from snapshot | +| 4.20.0.0 | `#9449`_ | Display associated resource name on storage pools objects | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5275`_ | vr: restart conntrackd instead of '/usr/sbin/conntrackd | -| | | -d' | +| 4.20.0.0 | `#9518`_ | framework/db: use HikariCP as default and improvements | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5292`_ | ui: Show host as unsecure in listview | +| 4.20.0.0 | `#9628`_ | framework/config,server: configkey caching | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4111`_ | API-call to declare host as Degraded | +| 4.20.0.0 | `#9591`_ | [VMware] Add support for VMware 8.0u2 (8.0.2.x) and 8.0u3 | +| | | (8.0.3.x) | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5269`_ | ui: fix capitalise filter | +| 4.20.0.0 | `#9634`_ | UI: list vms with details=min when attach a volume to vm | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5285`_ | ui: fix handle action API response | +| 4.20.0.0 | `#8683`_ | Bump org.apache.commons:commons-compress from 1.21 to | +| | | 1.26.0 | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5283`_ | ui: Fix failure in deletion of templates | +| 4.20.0.0 | `#9632`_ | linstor: update java-linstor dependency to 0.5.2 | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5278`_ | ui: Add 'on / off' to status icon and make it case | -| | | insensitive | +| 4.20.0.0 | `#9631`_ | Fix PR lint error caused by deps/install-non-oss.sh | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5272`_ | Add YouTube channel link in the README | +| 4.20.0.0 | `#7610`_ | Notify users when upgrades are available or restart is | +| | | required for network or VPC | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5262`_ | [TEST] - Test unit - Fix failing UI unit test main branch | +| 4.20.0.0 | `#9239`_ | Fix snapshot deletion on template creation failure | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5257`_ | ui: fix import instance form for recent changes | +| 4.20.0.0 | `#9236`_ | kvm: Present the UUID of the VM as serial through smbios | +| | | information | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5043`_ | Allow updating the storage/host tags of service offerings | +| 4.20.0.0 | `#9205`_ | updated install-non-oss with vmware v7.0 and v8.0 | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5241`_ | Improve HA logs | +| 4.20.0.0 | `#9116`_ | Testcases Added | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4714`_ | Cleaning up code and enhancing a few IP management logs | +| 4.20.0.0 | `#8958`_ | Update en.json | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5263`_ | ui: Fix failing UI | +| 4.20.0.0 | `#9629`_ | Add FelipeM525 to .asf.yaml as a collaborator | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5219`_ | [TEST] - Test unit - Fix failing UI unit test 4.15 branch | +| 4.20.0.0 | `#9206`_ | storage: fix private templates are not copied to new image | +| | | store | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5236`_ | server: fix VR health check in vmware basic zone | +| 4.20.0.0 | `#9567`_ | Add validation for secstorage.allowed.internal.sites | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5253`_ | UI - zone wizard - change the argument of params.ipv6dns2 | +| 4.20.0.0 | `#9568`_ | VR: remove vpn user info when apply vpn users list | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5252`_ | ui: fix import instance form root disk label | +| 4.20.0.0 | `#9578`_ | server: fix stopped vm volume migration check on local | +| | | volume attach | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4257`_ | remove the unnecessary check for tags when migrating | -| | | volumes | +| 4.20.0.0 | `#9588`_ | Updated listStoragePools response - added new managed | +| | | parameter | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4768`_ | display nics deviceid and order nics by deviceid on Nics | -| | | tab of insta… | +| 4.20.0.0 | `#9616`_ | Add minimum details parameter to Search View's listDomains | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5239`_ | Externalize KVM Agent storage's timeout configuration | +| 4.20.0.0 | `#9625`_ | SystemVM template changes - updated debian version & other | +| | | changes | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4959`_ | Improve logs on ConsoleProxyManagerImpl and refactor a few | -| | | process | +| 4.20.0.0 | `#9610`_ | engine-orchestration: fix issue for empty product in vm | +| | | metadata | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5224`_ | ui: submit form with false boolean params | +| 4.20.0.0 | `#9560`_ | linstor: set/unset allow-two-primaries and protocol on rc | +| | | level | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5205`_ | ui: fix create shared network with multi-zone | +| 4.20.0.0 | `#9627`_ | Update Debian version to 12 in systemvm welcome message | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5231`_ | api: Fix pagination for list PublicIPAddresses | +| 4.20.0.0 | `#9573`_ | Fix VGPU available devices listing | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5245`_ | ui: Update header notice if job failed | +| 4.20.0.0 | `#9617`_ | Fixed incorrect label in VRs and SVMs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5246`_ | ui: Fix comparator for boolean | +| 4.20.0.0 | `#9554`_ | ui: show guest networks for guest vlans list | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5247`_ | ui: Fix current for vmsnapshots | +| 4.20.0.0 | `#9575`_ | Fix userdata append header restrictions | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5237`_ | [UI] Add Shift key for noVNC consoles | +| 4.20.0.0 | `#8755`_ | Added support for storpool_qos service | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5075`_ | ui: vmware vm import-unmanage | +| 4.20.0.0 | `#8649`_ | Improve logs in primary storage removal process | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4616`_ | Add logs to api removeVpnUser | +| 4.20.0.0 | `#9600`_ | systemvm: have flags to check x86_64 to install specifics | +| | | for amd64 arch | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5225`_ | Fix of shrinking volumes with QCOW2 format | +| 4.20.0.0 | `#9125`_ | Fix NPE when sending copy command to least busy SSVM | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4766`_ | UI: Submit the form when press CTRL + ENTER | +| 4.20.0.0 | `#9255`_ | Add certificate validation to check headers | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5233`_ | ui bug fix: scalevm is disabled when vm is Stopped | +| 4.20.0.0 | `#9455`_ | Updated invalid parameter/value error with proper | +| | | exception | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5206`_ | UI: only display host information, if they are relevant | +| 4.20.0.0 | `#8743`_ | Fix `deleteAccount` API to prevent deletion of the caller | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5232`_ | ui: Fix refresh issue | +| 4.20.0.0 | `#8751`_ | Configuration to disable URL validation when registering | +| | | templates/ISOs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5186`_ | Remove condition that are prevent resizing for root | -| | | volumes (vmware) | +| 4.20.0.0 | `#9549`_ | New Feature: Enable/Disable Roles | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5119`_ | Externalize tls version and security protocols | -| | | configuration on mail sending | +| 4.20.0.0 | `#8609`_ | Build: drop EL7 support, support JRE17 for packages and | +| | | sonar check | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5163`_ | add entity-type to message when no UUID is found for a DB | -| | | ID | +| 4.20.0.0 | `#9572`_ | Update project account for all the events with project | +| | | account owner, except for create project event | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5214`_ | ui: Refresh after async job completed only on current / | -| | | parent page | +| 4.20.0.0 | `#9468`_ | [VMware] Disconnect/Detach config drive ISO (if exists) on | +| | | stop VM | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5221`_ | ui: Fix async poll job | +| 4.20.0.0 | `#9433`_ | [VMware] Update data disk controller same as the root disk | +| | | controller type when it is not set in the VM detail | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5222`_ | ui: Replace bulk delete icons | +| 4.20.0.0 | `#9589`_ | [UI] Add project toggle for buckets | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5210`_ | api: Add 'created' field to API response | +| 4.20.0.0 | `#9459`_ | Fix usage volume size after resizing | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5218`_ | Revert "Externalize kvm agent storage timeout | -| | | configuration" | +| 4.20.0.0 | `#9540`_ | Added domain path to all entities | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4782`_ | UI: Refactor async job polling codebase-wide | +| 4.20.0.0 | `#9329`_ | Add support for network data in Config Drive | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4585`_ | Externalize kvm agent storage timeout configuration | +| 4.20.0.0 | `#9571`_ | test: fix component tests test_acl_isolatednetwork and | +| | | test_acl_isolatednetwork_delete | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5213`_ | Do remove volume only on expunge | +| 4.20.0.0 | `#8832`_ | Fix snapshot scheduling with expired jobs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4640`_ | Added disk provisioning type support for VMWare | +| 4.20.0.0 | `#9163`_ | orchestration,hypervisor: allow custom manufacturer, | +| | | product for vm metadata | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5034`_ | UI: bulk action support for various resources | +| 4.20.0.0 | `#9422`_ | allow users to apply extraconfig on updating VMs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5211`_ | Fix deprecation of CIDR_LIST parameter | +| 4.20.0.0 | `#9542`_ | server: do not check affinity groups if no vm group | +| | | mappings | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4790`_ | Externalize secondary storage capacity threshold | +| 4.20.0.0 | `#8878`_ | Download Volume Snapshots | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5193`_ | kvm: pre-add 32 PCI controller for hot-plug issue on | -| | | ARM64/aarch64 | +| 4.20.0.0 | `#9550`_ | Fix to allow actions on the network if it belongs to a | +| | | project | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5012`_ | KVM NFS disk IO driver supporting IO_URING | +| 4.20.0.0 | `#9548`_ | UI: Add filter to list encrypted volumes | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5073`_ | systemvmtemplate: use latest LTS kernel from buster-ports | +| 4.20.0.0 | `#9545`_ | Fix Template and ISO upload events | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5184`_ | server: fix network access for addNicToVirtualMachine API | +| 4.20.0.0 | `#9553`_ | Fix main branch issues | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5030`_ | refactor: migrate vm with storage | +| 4.20.0.0 | `#9551`_ | UI: Improve router listing page | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5170`_ | vmware: fix migrate vm with volume | +| 4.20.0.0 | `#8689`_ | Fix being able to expunge a VM through | +| | | destroyVirtualMachine even when role rule does not allow | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5199`_ | UI: deploy VM - FIX missing custom iops field | +| 4.20.0.0 | `#9417`_ | linstor: Improve copyPhysicalDisk performance | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5197`_ | UI: fix NIC table on instance view | +| 4.20.0.0 | `#9264`_ | fix removeSecondaryStorageSelector response for docs | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5178`_ | [UI] zone wizard: change edit traffic type form of VMware | +| 4.20.0.0 | `#8556`_ | Allow deletion of system VM templates | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5144`_ | configdrive: fix some failures in | -| | | tests/component/test_configdrive.py | +| 4.20.0.0 | `#9225`_ | Improvements to quota tariffs APIs and UI | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5136`_ | apiserver : Ensure required parameters are not empty | +| 4.20.0.0 | `#9435`_ | NSX: add back removed code for NSX | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5064`_ | ui: refactor get api params in forms | +| 4.20.0.0 | `#8812`_ | Fix column from op_dc_ip_address_alloc not being | +| | | referenced correctly by its ORM class | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5133`_ | ui: refactor labels with tooltip in forms | +| 4.20.0.0 | `#9396`_ | created VPC message a little less misleading | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5182`_ | ui: Fix traversal to domain details via domain router-link | -| | | of a resource | +| 4.20.0.0 | `#9385`_ | add procedures procedure | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4575`_ | Enhance log messages with host name | +| 4.20.0.0 | `#9201`_ | Ensure affinity groups are honored when VMs are deployed | +| | | in parallel | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5183`_ | expunge vm: Allow expunging a VM in destroyed state | +| 4.20.0.0 | `#9487`_ | ui: rename autoscale instance group to simply autoscaling | +| | | group | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5139`_ | marvin: make deployDataCenter.py script compatible with | -| | | python 2 and 3 | +| 4.20.0.0 | `#9499`_ | test: fix component test | +| | | test_acl_sharednetwork_deployVM-impersonation.py | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4037`_ | Document cidrlist parameter deprecation | +| 4.20.0.0 | `#9340`_ | Support user resource name / displaytext with emoji, | +| | | unicode chars, and some sql exception msg improvements | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5165`_ | Prevent starting a VM in destroyed state (or any state but | -| | | Stopped) | +| 4.20.0.0 | `#9390`_ | libvirtstorageadaptor: better handle failed libvirt | +| | | storagepool destroy | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5167`_ | UI - zone wizard - fix undefined property when setting RBD | -| | | primary storage | +| 4.20.0.0 | `#9447`_ | Fix snapshot chain being deleted on XenServer | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5176`_ | [UI] secondary storage - Display text and change the badge | -| | | color of the Read-only column | +| 4.20.0.0 | `#8615`_ | Add UI to view and download usage records | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5173`_ | Some changes of the german translation | +| 4.20.0.0 | `#9450`_ | packaging: bundle latest cmk x86 build with deb and rpm | +| | | packages | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5164`_ | kvm: fix VM HA on zone-wide storage pools | +| 4.20.0.0 | `#9426`_ | test: improve purge expunged resources b/g task testcase | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5154`_ | Fix NPE when no recipients configured for sending alerts | +| 4.20.0.0 | `#9419`_ | API: Fix missing keys in listZonesMetrics response | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5142`_ | Fix NPE during removal of VM from Network | +| 4.20.0.0 | `#9399`_ | ui: vm metrics note about behaviour across hypervisors | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5171`_ | Updated some offensive words in kubernetes plugin/service | -| | | with inclusive words/terms. | +| 4.20.0.0 | `#9434`_ | Fixup CKS UI for external managed clusters | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5125`_ | volume: Fix deletion of Uploaded volumes | +| 4.20.0.0 | `#9458`_ | UI: Display Firewall, LB and Port Forwarding rules tab for | +| | | CKS clusters deployed on isolated networks | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4796`_ | db, server: refactor host_view to prevent duplicate | -| | | entries | +| 4.20.0.0 | `#9442`_ | Fix removal of usage records | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4843`_ | ui: deployvm - Add option to stay on page | +| 4.20.0.0 | `#9437`_ | Add systemvmtemplate arm64 build support | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5162`_ | On Upgrade, Replace the DB properties having master and | -| | | slave(s), with source and replica(s) respectively for | -| | | inclusiveness | +| 4.20.0.0 | `#8739`_ | [4.20] VR: fix issue if userdata is binary data | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5106`_ | tests: Fix test failures for Local storage and Basic zones | +| 4.20.0.0 | `#9043`_ | Enhancement in the accuracy of the logs regarding the | +| | | capacity, usage, and threshold of secondary storages | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5146`_ | (auto) formatting and cleanup fixes for test_volumes | +| 4.20.0.0 | `#9062`_ | Change exception when orchestrating VM start | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5140`_ | Display proper names in error message | +| 4.20.0.0 | `#8833`_ | Fix link to removed volumes being shown in info card and | +| | | list view | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#4886`_ | server: list routers by healthchecksfailed | +| 4.20.0.0 | `#9409`_ | ui: add new API docs tab | +-------------------------+----------+------------------------------------------------------------+ -| 4.16.0.0 | `#5128`_ | tests: Skip test_persistent_networks if kvm and ovs | +| 4.20.0.0 | `#9402`_ | Icon changed for control-outlined | +-------------------------+----------+------------------------------------------------------------+ -328 Issues listed +151 Issues listed -.. _`#5665`: https://github.com/apache/cloudstack/pull/5665 -.. _`#5659`: https://github.com/apache/cloudstack/pull/5659 -.. _`#5661`: https://github.com/apache/cloudstack/pull/5661 -.. _`#5645`: https://github.com/apache/cloudstack/pull/5645 -.. _`#5657`: https://github.com/apache/cloudstack/pull/5657 -.. _`#5642`: https://github.com/apache/cloudstack/pull/5642 -.. _`#5646`: https://github.com/apache/cloudstack/pull/5646 -.. _`#5629`: https://github.com/apache/cloudstack/pull/5629 -.. _`#5644`: https://github.com/apache/cloudstack/pull/5644 -.. _`#5638`: https://github.com/apache/cloudstack/pull/5638 -.. _`#5643`: https://github.com/apache/cloudstack/pull/5643 -.. _`#5624`: https://github.com/apache/cloudstack/pull/5624 -.. _`#5586`: https://github.com/apache/cloudstack/pull/5586 -.. _`#5621`: https://github.com/apache/cloudstack/pull/5621 -.. _`#5593`: https://github.com/apache/cloudstack/pull/5593 -.. _`#5614`: https://github.com/apache/cloudstack/pull/5614 -.. _`#5612`: https://github.com/apache/cloudstack/pull/5612 -.. _`#5608`: https://github.com/apache/cloudstack/pull/5608 -.. _`#5609`: https://github.com/apache/cloudstack/pull/5609 -.. _`#5607`: https://github.com/apache/cloudstack/pull/5607 -.. _`#5599`: https://github.com/apache/cloudstack/pull/5599 -.. _`#5597`: https://github.com/apache/cloudstack/pull/5597 -.. _`#5598`: https://github.com/apache/cloudstack/pull/5598 -.. _`#5601`: https://github.com/apache/cloudstack/pull/5601 -.. _`#5585`: https://github.com/apache/cloudstack/pull/5585 -.. _`#5583`: https://github.com/apache/cloudstack/pull/5583 -.. _`#5580`: https://github.com/apache/cloudstack/pull/5580 -.. _`#5582`: https://github.com/apache/cloudstack/pull/5582 -.. _`#5575`: https://github.com/apache/cloudstack/pull/5575 -.. _`#5577`: https://github.com/apache/cloudstack/pull/5577 -.. _`#5573`: https://github.com/apache/cloudstack/pull/5573 -.. _`#5574`: https://github.com/apache/cloudstack/pull/5574 -.. _`#5571`: https://github.com/apache/cloudstack/pull/5571 -.. _`#5565`: https://github.com/apache/cloudstack/pull/5565 -.. _`#5572`: https://github.com/apache/cloudstack/pull/5572 -.. _`#5569`: https://github.com/apache/cloudstack/pull/5569 -.. _`#5568`: https://github.com/apache/cloudstack/pull/5568 -.. _`#5561`: https://github.com/apache/cloudstack/pull/5561 -.. _`#5560`: https://github.com/apache/cloudstack/pull/5560 -.. _`#5557`: https://github.com/apache/cloudstack/pull/5557 -.. _`#5410`: https://github.com/apache/cloudstack/pull/5410 -.. _`#5554`: https://github.com/apache/cloudstack/pull/5554 -.. _`#5543`: https://github.com/apache/cloudstack/pull/5543 -.. _`#4329`: https://github.com/apache/cloudstack/pull/4329 -.. _`#5551`: https://github.com/apache/cloudstack/pull/5551 -.. _`#5542`: https://github.com/apache/cloudstack/pull/5542 -.. _`#5540`: https://github.com/apache/cloudstack/pull/5540 -.. _`#5539`: https://github.com/apache/cloudstack/pull/5539 -.. _`#5471`: https://github.com/apache/cloudstack/pull/5471 -.. _`#5547`: https://github.com/apache/cloudstack/pull/5547 -.. _`#5541`: https://github.com/apache/cloudstack/pull/5541 -.. _`#5546`: https://github.com/apache/cloudstack/pull/5546 -.. _`#5530`: https://github.com/apache/cloudstack/pull/5530 -.. _`#5513`: https://github.com/apache/cloudstack/pull/5513 -.. _`#5501`: https://github.com/apache/cloudstack/pull/5501 -.. _`#5532`: https://github.com/apache/cloudstack/pull/5532 -.. _`#5446`: https://github.com/apache/cloudstack/pull/5446 -.. _`#5470`: https://github.com/apache/cloudstack/pull/5470 -.. _`#5511`: https://github.com/apache/cloudstack/pull/5511 -.. _`#5510`: https://github.com/apache/cloudstack/pull/5510 -.. _`#5504`: https://github.com/apache/cloudstack/pull/5504 -.. _`#5537`: https://github.com/apache/cloudstack/pull/5537 -.. _`#5526`: https://github.com/apache/cloudstack/pull/5526 -.. _`#5521`: https://github.com/apache/cloudstack/pull/5521 -.. _`#4215`: https://github.com/apache/cloudstack/pull/4215 -.. _`#5522`: https://github.com/apache/cloudstack/pull/5522 -.. _`#5515`: https://github.com/apache/cloudstack/pull/5515 -.. _`#4826`: https://github.com/apache/cloudstack/pull/4826 -.. _`#5520`: https://github.com/apache/cloudstack/pull/5520 -.. _`#5469`: https://github.com/apache/cloudstack/pull/5469 -.. _`#4617`: https://github.com/apache/cloudstack/pull/4617 -.. _`#5503`: https://github.com/apache/cloudstack/pull/5503 -.. _`#5455`: https://github.com/apache/cloudstack/pull/5455 -.. _`#5507`: https://github.com/apache/cloudstack/pull/5507 -.. _`#5505`: https://github.com/apache/cloudstack/pull/5505 -.. _`#5428`: https://github.com/apache/cloudstack/pull/5428 -.. _`#5483`: https://github.com/apache/cloudstack/pull/5483 -.. _`#5419`: https://github.com/apache/cloudstack/pull/5419 -.. _`#5480`: https://github.com/apache/cloudstack/pull/5480 -.. _`#5490`: https://github.com/apache/cloudstack/pull/5490 -.. _`#3804`: https://github.com/apache/cloudstack/pull/3804 -.. _`#5496`: https://github.com/apache/cloudstack/pull/5496 -.. _`#5495`: https://github.com/apache/cloudstack/pull/5495 -.. _`#5492`: https://github.com/apache/cloudstack/pull/5492 -.. _`#5486`: https://github.com/apache/cloudstack/pull/5486 -.. _`#5488`: https://github.com/apache/cloudstack/pull/5488 -.. _`#5481`: https://github.com/apache/cloudstack/pull/5481 -.. _`#5485`: https://github.com/apache/cloudstack/pull/5485 -.. _`#5454`: https://github.com/apache/cloudstack/pull/5454 -.. _`#4890`: https://github.com/apache/cloudstack/pull/4890 -.. _`#5458`: https://github.com/apache/cloudstack/pull/5458 -.. _`#5472`: https://github.com/apache/cloudstack/pull/5472 -.. _`#5468`: https://github.com/apache/cloudstack/pull/5468 -.. _`#5474`: https://github.com/apache/cloudstack/pull/5474 -.. _`#5459`: https://github.com/apache/cloudstack/pull/5459 -.. _`#5476`: https://github.com/apache/cloudstack/pull/5476 -.. _`#5411`: https://github.com/apache/cloudstack/pull/5411 -.. _`#5464`: https://github.com/apache/cloudstack/pull/5464 -.. _`#4634`: https://github.com/apache/cloudstack/pull/4634 -.. _`#5465`: https://github.com/apache/cloudstack/pull/5465 -.. _`#5449`: https://github.com/apache/cloudstack/pull/5449 -.. _`#5463`: https://github.com/apache/cloudstack/pull/5463 -.. _`#5460`: https://github.com/apache/cloudstack/pull/5460 -.. _`#5453`: https://github.com/apache/cloudstack/pull/5453 -.. _`#5369`: https://github.com/apache/cloudstack/pull/5369 -.. _`#5420`: https://github.com/apache/cloudstack/pull/5420 -.. _`#5448`: https://github.com/apache/cloudstack/pull/5448 -.. _`#5456`: https://github.com/apache/cloudstack/pull/5456 -.. _`#4994`: https://github.com/apache/cloudstack/pull/4994 -.. _`#4635`: https://github.com/apache/cloudstack/pull/4635 -.. _`#5388`: https://github.com/apache/cloudstack/pull/5388 -.. _`#5451`: https://github.com/apache/cloudstack/pull/5451 -.. _`#5424`: https://github.com/apache/cloudstack/pull/5424 -.. _`#5447`: https://github.com/apache/cloudstack/pull/5447 -.. _`#5157`: https://github.com/apache/cloudstack/pull/5157 -.. _`#5425`: https://github.com/apache/cloudstack/pull/5425 -.. _`#4741`: https://github.com/apache/cloudstack/pull/4741 -.. _`#5450`: https://github.com/apache/cloudstack/pull/5450 -.. _`#5417`: https://github.com/apache/cloudstack/pull/5417 -.. _`#5421`: https://github.com/apache/cloudstack/pull/5421 -.. _`#5439`: https://github.com/apache/cloudstack/pull/5439 -.. _`#5423`: https://github.com/apache/cloudstack/pull/5423 -.. _`#5395`: https://github.com/apache/cloudstack/pull/5395 -.. _`#5441`: https://github.com/apache/cloudstack/pull/5441 -.. _`#5438`: https://github.com/apache/cloudstack/pull/5438 -.. _`#5437`: https://github.com/apache/cloudstack/pull/5437 -.. _`#5435`: https://github.com/apache/cloudstack/pull/5435 -.. _`#5432`: https://github.com/apache/cloudstack/pull/5432 -.. _`#5427`: https://github.com/apache/cloudstack/pull/5427 -.. _`#5431`: https://github.com/apache/cloudstack/pull/5431 -.. _`#5429`: https://github.com/apache/cloudstack/pull/5429 -.. _`#5398`: https://github.com/apache/cloudstack/pull/5398 -.. _`#5358`: https://github.com/apache/cloudstack/pull/5358 -.. _`#5416`: https://github.com/apache/cloudstack/pull/5416 -.. _`#5067`: https://github.com/apache/cloudstack/pull/5067 -.. _`#3975`: https://github.com/apache/cloudstack/pull/3975 -.. _`#5103`: https://github.com/apache/cloudstack/pull/5103 -.. _`#5401`: https://github.com/apache/cloudstack/pull/5401 -.. _`#5396`: https://github.com/apache/cloudstack/pull/5396 -.. _`#5390`: https://github.com/apache/cloudstack/pull/5390 -.. _`#4534`: https://github.com/apache/cloudstack/pull/4534 -.. _`#5402`: https://github.com/apache/cloudstack/pull/5402 -.. _`#5387`: https://github.com/apache/cloudstack/pull/5387 -.. _`#5408`: https://github.com/apache/cloudstack/pull/5408 -.. _`#5066`: https://github.com/apache/cloudstack/pull/5066 -.. _`#5404`: https://github.com/apache/cloudstack/pull/5404 -.. _`#5394`: https://github.com/apache/cloudstack/pull/5394 -.. _`#5259`: https://github.com/apache/cloudstack/pull/5259 -.. _`#5307`: https://github.com/apache/cloudstack/pull/5307 -.. _`#5339`: https://github.com/apache/cloudstack/pull/5339 -.. _`#5333`: https://github.com/apache/cloudstack/pull/5333 -.. _`#5403`: https://github.com/apache/cloudstack/pull/5403 -.. _`#5082`: https://github.com/apache/cloudstack/pull/5082 -.. _`#5399`: https://github.com/apache/cloudstack/pull/5399 -.. _`#5376`: https://github.com/apache/cloudstack/pull/5376 -.. _`#5375`: https://github.com/apache/cloudstack/pull/5375 -.. _`#5374`: https://github.com/apache/cloudstack/pull/5374 -.. _`#5379`: https://github.com/apache/cloudstack/pull/5379 -.. _`#5380`: https://github.com/apache/cloudstack/pull/5380 -.. _`#5392`: https://github.com/apache/cloudstack/pull/5392 -.. _`#4852`: https://github.com/apache/cloudstack/pull/4852 -.. _`#5393`: https://github.com/apache/cloudstack/pull/5393 -.. _`#5373`: https://github.com/apache/cloudstack/pull/5373 -.. _`#5335`: https://github.com/apache/cloudstack/pull/5335 -.. _`#5349`: https://github.com/apache/cloudstack/pull/5349 -.. _`#5366`: https://github.com/apache/cloudstack/pull/5366 -.. _`#5385`: https://github.com/apache/cloudstack/pull/5385 -.. _`#5371`: https://github.com/apache/cloudstack/pull/5371 -.. _`#5311`: https://github.com/apache/cloudstack/pull/5311 -.. _`#5377`: https://github.com/apache/cloudstack/pull/5377 -.. _`#5368`: https://github.com/apache/cloudstack/pull/5368 -.. _`#5364`: https://github.com/apache/cloudstack/pull/5364 -.. _`#4701`: https://github.com/apache/cloudstack/pull/4701 -.. _`#5384`: https://github.com/apache/cloudstack/pull/5384 -.. _`#5356`: https://github.com/apache/cloudstack/pull/5356 -.. _`#1257`: https://github.com/apache/cloudstack/pull/1257 -.. _`#5367`: https://github.com/apache/cloudstack/pull/5367 -.. _`#5360`: https://github.com/apache/cloudstack/pull/5360 -.. _`#5357`: https://github.com/apache/cloudstack/pull/5357 -.. _`#4570`: https://github.com/apache/cloudstack/pull/4570 -.. _`#5187`: https://github.com/apache/cloudstack/pull/5187 -.. _`#5319`: https://github.com/apache/cloudstack/pull/5319 -.. _`#5351`: https://github.com/apache/cloudstack/pull/5351 -.. _`#4662`: https://github.com/apache/cloudstack/pull/4662 -.. _`#5354`: https://github.com/apache/cloudstack/pull/5354 -.. _`#5359`: https://github.com/apache/cloudstack/pull/5359 -.. _`#5337`: https://github.com/apache/cloudstack/pull/5337 -.. _`#5345`: https://github.com/apache/cloudstack/pull/5345 -.. _`#5341`: https://github.com/apache/cloudstack/pull/5341 -.. _`#5355`: https://github.com/apache/cloudstack/pull/5355 -.. _`#4586`: https://github.com/apache/cloudstack/pull/4586 -.. _`#4878`: https://github.com/apache/cloudstack/pull/4878 -.. _`#5321`: https://github.com/apache/cloudstack/pull/5321 -.. _`#5194`: https://github.com/apache/cloudstack/pull/5194 -.. _`#5331`: https://github.com/apache/cloudstack/pull/5331 -.. _`#5348`: https://github.com/apache/cloudstack/pull/5348 -.. _`#5328`: https://github.com/apache/cloudstack/pull/5328 -.. _`#5346`: https://github.com/apache/cloudstack/pull/5346 -.. _`#4618`: https://github.com/apache/cloudstack/pull/4618 -.. _`#5342`: https://github.com/apache/cloudstack/pull/5342 -.. _`#5326`: https://github.com/apache/cloudstack/pull/5326 -.. _`#5110`: https://github.com/apache/cloudstack/pull/5110 -.. _`#5318`: https://github.com/apache/cloudstack/pull/5318 -.. _`#5217`: https://github.com/apache/cloudstack/pull/5217 -.. _`#5329`: https://github.com/apache/cloudstack/pull/5329 -.. _`#5303`: https://github.com/apache/cloudstack/pull/5303 -.. _`#5320`: https://github.com/apache/cloudstack/pull/5320 -.. _`#5327`: https://github.com/apache/cloudstack/pull/5327 -.. _`#5317`: https://github.com/apache/cloudstack/pull/5317 -.. _`#5158`: https://github.com/apache/cloudstack/pull/5158 -.. _`#5323`: https://github.com/apache/cloudstack/pull/5323 -.. _`#5325`: https://github.com/apache/cloudstack/pull/5325 -.. _`#4776`: https://github.com/apache/cloudstack/pull/4776 -.. _`#4780`: https://github.com/apache/cloudstack/pull/4780 -.. _`#4399`: https://github.com/apache/cloudstack/pull/4399 -.. _`#5312`: https://github.com/apache/cloudstack/pull/5312 -.. _`#5304`: https://github.com/apache/cloudstack/pull/5304 -.. _`#5273`: https://github.com/apache/cloudstack/pull/5273 -.. _`#5258`: https://github.com/apache/cloudstack/pull/5258 -.. _`#5274`: https://github.com/apache/cloudstack/pull/5274 -.. _`#5242`: https://github.com/apache/cloudstack/pull/5242 -.. _`#4630`: https://github.com/apache/cloudstack/pull/4630 -.. _`#5305`: https://github.com/apache/cloudstack/pull/5305 -.. _`#4699`: https://github.com/apache/cloudstack/pull/4699 -.. _`#5249`: https://github.com/apache/cloudstack/pull/5249 -.. _`#5052`: https://github.com/apache/cloudstack/pull/5052 -.. _`#5301`: https://github.com/apache/cloudstack/pull/5301 -.. _`#5289`: https://github.com/apache/cloudstack/pull/5289 -.. _`#4885`: https://github.com/apache/cloudstack/pull/4885 -.. _`#5298`: https://github.com/apache/cloudstack/pull/5298 -.. _`#5299`: https://github.com/apache/cloudstack/pull/5299 -.. _`#4378`: https://github.com/apache/cloudstack/pull/4378 -.. _`#5295`: https://github.com/apache/cloudstack/pull/5295 -.. _`#5254`: https://github.com/apache/cloudstack/pull/5254 -.. _`#4551`: https://github.com/apache/cloudstack/pull/4551 -.. _`#4685`: https://github.com/apache/cloudstack/pull/4685 -.. _`#4737`: https://github.com/apache/cloudstack/pull/4737 -.. _`#5270`: https://github.com/apache/cloudstack/pull/5270 -.. _`#5288`: https://github.com/apache/cloudstack/pull/5288 -.. _`#5287`: https://github.com/apache/cloudstack/pull/5287 -.. _`#5282`: https://github.com/apache/cloudstack/pull/5282 -.. _`#5275`: https://github.com/apache/cloudstack/pull/5275 -.. _`#5292`: https://github.com/apache/cloudstack/pull/5292 -.. _`#4111`: https://github.com/apache/cloudstack/pull/4111 -.. _`#5269`: https://github.com/apache/cloudstack/pull/5269 -.. _`#5285`: https://github.com/apache/cloudstack/pull/5285 -.. _`#5283`: https://github.com/apache/cloudstack/pull/5283 -.. _`#5278`: https://github.com/apache/cloudstack/pull/5278 -.. _`#5272`: https://github.com/apache/cloudstack/pull/5272 -.. _`#5262`: https://github.com/apache/cloudstack/pull/5262 -.. _`#5257`: https://github.com/apache/cloudstack/pull/5257 -.. _`#5043`: https://github.com/apache/cloudstack/pull/5043 -.. _`#5241`: https://github.com/apache/cloudstack/pull/5241 -.. _`#4714`: https://github.com/apache/cloudstack/pull/4714 -.. _`#5263`: https://github.com/apache/cloudstack/pull/5263 -.. _`#5219`: https://github.com/apache/cloudstack/pull/5219 -.. _`#5236`: https://github.com/apache/cloudstack/pull/5236 -.. _`#5253`: https://github.com/apache/cloudstack/pull/5253 -.. _`#5252`: https://github.com/apache/cloudstack/pull/5252 -.. _`#4257`: https://github.com/apache/cloudstack/pull/4257 -.. _`#4768`: https://github.com/apache/cloudstack/pull/4768 -.. _`#5239`: https://github.com/apache/cloudstack/pull/5239 -.. _`#4959`: https://github.com/apache/cloudstack/pull/4959 -.. _`#5224`: https://github.com/apache/cloudstack/pull/5224 -.. _`#5205`: https://github.com/apache/cloudstack/pull/5205 -.. _`#5231`: https://github.com/apache/cloudstack/pull/5231 -.. _`#5245`: https://github.com/apache/cloudstack/pull/5245 -.. _`#5246`: https://github.com/apache/cloudstack/pull/5246 -.. _`#5247`: https://github.com/apache/cloudstack/pull/5247 -.. _`#5237`: https://github.com/apache/cloudstack/pull/5237 -.. _`#5075`: https://github.com/apache/cloudstack/pull/5075 -.. _`#4616`: https://github.com/apache/cloudstack/pull/4616 -.. _`#5225`: https://github.com/apache/cloudstack/pull/5225 -.. _`#4766`: https://github.com/apache/cloudstack/pull/4766 -.. _`#5233`: https://github.com/apache/cloudstack/pull/5233 -.. _`#5206`: https://github.com/apache/cloudstack/pull/5206 -.. _`#5232`: https://github.com/apache/cloudstack/pull/5232 -.. _`#5186`: https://github.com/apache/cloudstack/pull/5186 -.. _`#5149`: https://github.com/apache/cloudstack/pull/5149 -.. _`#5119`: https://github.com/apache/cloudstack/pull/5119 -.. _`#5163`: https://github.com/apache/cloudstack/pull/5163 -.. _`#5214`: https://github.com/apache/cloudstack/pull/5214 -.. _`#5221`: https://github.com/apache/cloudstack/pull/5221 -.. _`#5222`: https://github.com/apache/cloudstack/pull/5222 -.. _`#5210`: https://github.com/apache/cloudstack/pull/5210 -.. _`#5218`: https://github.com/apache/cloudstack/pull/5218 -.. _`#4782`: https://github.com/apache/cloudstack/pull/4782 -.. _`#4585`: https://github.com/apache/cloudstack/pull/4585 -.. _`#5213`: https://github.com/apache/cloudstack/pull/5213 -.. _`#4640`: https://github.com/apache/cloudstack/pull/4640 -.. _`#5034`: https://github.com/apache/cloudstack/pull/5034 -.. _`#5211`: https://github.com/apache/cloudstack/pull/5211 -.. _`#4790`: https://github.com/apache/cloudstack/pull/4790 -.. _`#5193`: https://github.com/apache/cloudstack/pull/5193 -.. _`#5012`: https://github.com/apache/cloudstack/pull/5012 -.. _`#5073`: https://github.com/apache/cloudstack/pull/5073 -.. _`#5184`: https://github.com/apache/cloudstack/pull/5184 -.. _`#5030`: https://github.com/apache/cloudstack/pull/5030 -.. _`#5170`: https://github.com/apache/cloudstack/pull/5170 -.. _`#5199`: https://github.com/apache/cloudstack/pull/5199 -.. _`#5197`: https://github.com/apache/cloudstack/pull/5197 -.. _`#5178`: https://github.com/apache/cloudstack/pull/5178 -.. _`#5144`: https://github.com/apache/cloudstack/pull/5144 -.. _`#5136`: https://github.com/apache/cloudstack/pull/5136 -.. _`#5064`: https://github.com/apache/cloudstack/pull/5064 -.. _`#5133`: https://github.com/apache/cloudstack/pull/5133 -.. _`#5182`: https://github.com/apache/cloudstack/pull/5182 -.. _`#4575`: https://github.com/apache/cloudstack/pull/4575 -.. _`#5183`: https://github.com/apache/cloudstack/pull/5183 -.. _`#5139`: https://github.com/apache/cloudstack/pull/5139 -.. _`#4037`: https://github.com/apache/cloudstack/pull/4037 -.. _`#5165`: https://github.com/apache/cloudstack/pull/5165 -.. _`#5167`: https://github.com/apache/cloudstack/pull/5167 -.. _`#5176`: https://github.com/apache/cloudstack/pull/5176 -.. _`#5173`: https://github.com/apache/cloudstack/pull/5173 -.. _`#5164`: https://github.com/apache/cloudstack/pull/5164 -.. _`#5154`: https://github.com/apache/cloudstack/pull/5154 -.. _`#5142`: https://github.com/apache/cloudstack/pull/5142 -.. _`#5171`: https://github.com/apache/cloudstack/pull/5171 -.. _`#5125`: https://github.com/apache/cloudstack/pull/5125 -.. _`#4796`: https://github.com/apache/cloudstack/pull/4796 -.. _`#4843`: https://github.com/apache/cloudstack/pull/4843 -.. _`#5162`: https://github.com/apache/cloudstack/pull/5162 -.. _`#5106`: https://github.com/apache/cloudstack/pull/5106 -.. _`#5146`: https://github.com/apache/cloudstack/pull/5146 -.. _`#5140`: https://github.com/apache/cloudstack/pull/5140 -.. _`#4886`: https://github.com/apache/cloudstack/pull/4886 -.. _`#5128`: https://github.com/apache/cloudstack/pull/5128 +.. _`#8911`: https://github.com/apache/cloudstack/pull/8911 +.. _`#9751`: https://github.com/apache/cloudstack/pull/9751 +.. _`#9731`: https://github.com/apache/cloudstack/pull/9731 +.. _`#9195`: https://github.com/apache/cloudstack/pull/9195 +.. _`#9738`: https://github.com/apache/cloudstack/pull/9738 +.. _`#9723`: https://github.com/apache/cloudstack/pull/9723 +.. _`#9739`: https://github.com/apache/cloudstack/pull/9739 +.. _`#7650`: https://github.com/apache/cloudstack/pull/7650 +.. _`#8588`: https://github.com/apache/cloudstack/pull/8588 +.. _`#9664`: https://github.com/apache/cloudstack/pull/9664 +.. _`#9559`: https://github.com/apache/cloudstack/pull/9559 +.. _`#9374`: https://github.com/apache/cloudstack/pull/9374 +.. _`#9720`: https://github.com/apache/cloudstack/pull/9720 +.. _`#9596`: https://github.com/apache/cloudstack/pull/9596 +.. _`#9711`: https://github.com/apache/cloudstack/pull/9711 +.. _`#9006`: https://github.com/apache/cloudstack/pull/9006 +.. _`#9637`: https://github.com/apache/cloudstack/pull/9637 +.. _`#8846`: https://github.com/apache/cloudstack/pull/8846 +.. _`#9714`: https://github.com/apache/cloudstack/pull/9714 +.. _`#9636`: https://github.com/apache/cloudstack/pull/9636 +.. _`#9699`: https://github.com/apache/cloudstack/pull/9699 +.. _`#9698`: https://github.com/apache/cloudstack/pull/9698 +.. _`#9700`: https://github.com/apache/cloudstack/pull/9700 +.. _`#9563`: https://github.com/apache/cloudstack/pull/9563 +.. _`#9676`: https://github.com/apache/cloudstack/pull/9676 +.. _`#9200`: https://github.com/apache/cloudstack/pull/9200 +.. _`#9557`: https://github.com/apache/cloudstack/pull/9557 +.. _`#8503`: https://github.com/apache/cloudstack/pull/8503 +.. _`#9696`: https://github.com/apache/cloudstack/pull/9696 +.. _`#9680`: https://github.com/apache/cloudstack/pull/9680 +.. _`#9655`: https://github.com/apache/cloudstack/pull/9655 +.. _`#9681`: https://github.com/apache/cloudstack/pull/9681 +.. _`#9669`: https://github.com/apache/cloudstack/pull/9669 +.. _`#9661`: https://github.com/apache/cloudstack/pull/9661 +.. _`#9675`: https://github.com/apache/cloudstack/pull/9675 +.. _`#9663`: https://github.com/apache/cloudstack/pull/9663 +.. _`#9585`: https://github.com/apache/cloudstack/pull/9585 +.. _`#9662`: https://github.com/apache/cloudstack/pull/9662 +.. _`#9509`: https://github.com/apache/cloudstack/pull/9509 +.. _`#9656`: https://github.com/apache/cloudstack/pull/9656 +.. _`#9188`: https://github.com/apache/cloudstack/pull/9188 +.. _`#9566`: https://github.com/apache/cloudstack/pull/9566 +.. _`#8924`: https://github.com/apache/cloudstack/pull/8924 +.. _`#9461`: https://github.com/apache/cloudstack/pull/9461 +.. _`#9633`: https://github.com/apache/cloudstack/pull/9633 +.. _`#9652`: https://github.com/apache/cloudstack/pull/9652 +.. _`#9528`: https://github.com/apache/cloudstack/pull/9528 +.. _`#8906`: https://github.com/apache/cloudstack/pull/8906 +.. _`#9107`: https://github.com/apache/cloudstack/pull/9107 +.. _`#8511`: https://github.com/apache/cloudstack/pull/8511 +.. _`#9639`: https://github.com/apache/cloudstack/pull/9639 +.. _`#9619`: https://github.com/apache/cloudstack/pull/9619 +.. _`#9647`: https://github.com/apache/cloudstack/pull/9647 +.. _`#9428`: https://github.com/apache/cloudstack/pull/9428 +.. _`#9470`: https://github.com/apache/cloudstack/pull/9470 +.. _`#9451`: https://github.com/apache/cloudstack/pull/9451 +.. _`#8389`: https://github.com/apache/cloudstack/pull/8389 +.. _`#9208`: https://github.com/apache/cloudstack/pull/9208 +.. _`#9415`: https://github.com/apache/cloudstack/pull/9415 +.. _`#9624`: https://github.com/apache/cloudstack/pull/9624 +.. _`#8925`: https://github.com/apache/cloudstack/pull/8925 +.. _`#9543`: https://github.com/apache/cloudstack/pull/9543 +.. _`#9569`: https://github.com/apache/cloudstack/pull/9569 +.. _`#9449`: https://github.com/apache/cloudstack/pull/9449 +.. _`#9518`: https://github.com/apache/cloudstack/pull/9518 +.. _`#9628`: https://github.com/apache/cloudstack/pull/9628 +.. _`#9591`: https://github.com/apache/cloudstack/pull/9591 +.. _`#9634`: https://github.com/apache/cloudstack/pull/9634 +.. _`#8683`: https://github.com/apache/cloudstack/pull/8683 +.. _`#9632`: https://github.com/apache/cloudstack/pull/9632 +.. _`#9631`: https://github.com/apache/cloudstack/pull/9631 +.. _`#7610`: https://github.com/apache/cloudstack/pull/7610 +.. _`#9239`: https://github.com/apache/cloudstack/pull/9239 +.. _`#9236`: https://github.com/apache/cloudstack/pull/9236 +.. _`#9205`: https://github.com/apache/cloudstack/pull/9205 +.. _`#9116`: https://github.com/apache/cloudstack/pull/9116 +.. _`#8958`: https://github.com/apache/cloudstack/pull/8958 +.. _`#9629`: https://github.com/apache/cloudstack/pull/9629 +.. _`#9206`: https://github.com/apache/cloudstack/pull/9206 +.. _`#9567`: https://github.com/apache/cloudstack/pull/9567 +.. _`#9568`: https://github.com/apache/cloudstack/pull/9568 +.. _`#9578`: https://github.com/apache/cloudstack/pull/9578 +.. _`#9588`: https://github.com/apache/cloudstack/pull/9588 +.. _`#9616`: https://github.com/apache/cloudstack/pull/9616 +.. _`#9625`: https://github.com/apache/cloudstack/pull/9625 +.. _`#9610`: https://github.com/apache/cloudstack/pull/9610 +.. _`#9560`: https://github.com/apache/cloudstack/pull/9560 +.. _`#9627`: https://github.com/apache/cloudstack/pull/9627 +.. _`#9573`: https://github.com/apache/cloudstack/pull/9573 +.. _`#9617`: https://github.com/apache/cloudstack/pull/9617 +.. _`#9554`: https://github.com/apache/cloudstack/pull/9554 +.. _`#9575`: https://github.com/apache/cloudstack/pull/9575 +.. _`#8755`: https://github.com/apache/cloudstack/pull/8755 +.. _`#8649`: https://github.com/apache/cloudstack/pull/8649 +.. _`#9600`: https://github.com/apache/cloudstack/pull/9600 +.. _`#9125`: https://github.com/apache/cloudstack/pull/9125 +.. _`#9255`: https://github.com/apache/cloudstack/pull/9255 +.. _`#9455`: https://github.com/apache/cloudstack/pull/9455 +.. _`#8743`: https://github.com/apache/cloudstack/pull/8743 +.. _`#8751`: https://github.com/apache/cloudstack/pull/8751 +.. _`#9549`: https://github.com/apache/cloudstack/pull/9549 +.. _`#8609`: https://github.com/apache/cloudstack/pull/8609 +.. _`#9572`: https://github.com/apache/cloudstack/pull/9572 +.. _`#9468`: https://github.com/apache/cloudstack/pull/9468 +.. _`#9433`: https://github.com/apache/cloudstack/pull/9433 +.. _`#9589`: https://github.com/apache/cloudstack/pull/9589 +.. _`#9459`: https://github.com/apache/cloudstack/pull/9459 +.. _`#9540`: https://github.com/apache/cloudstack/pull/9540 +.. _`#9329`: https://github.com/apache/cloudstack/pull/9329 +.. _`#9571`: https://github.com/apache/cloudstack/pull/9571 +.. _`#8832`: https://github.com/apache/cloudstack/pull/8832 +.. _`#9163`: https://github.com/apache/cloudstack/pull/9163 +.. _`#9422`: https://github.com/apache/cloudstack/pull/9422 +.. _`#9542`: https://github.com/apache/cloudstack/pull/9542 +.. _`#8878`: https://github.com/apache/cloudstack/pull/8878 +.. _`#9550`: https://github.com/apache/cloudstack/pull/9550 +.. _`#9548`: https://github.com/apache/cloudstack/pull/9548 +.. _`#9545`: https://github.com/apache/cloudstack/pull/9545 +.. _`#9553`: https://github.com/apache/cloudstack/pull/9553 +.. _`#9551`: https://github.com/apache/cloudstack/pull/9551 +.. _`#8689`: https://github.com/apache/cloudstack/pull/8689 +.. _`#9417`: https://github.com/apache/cloudstack/pull/9417 +.. _`#9264`: https://github.com/apache/cloudstack/pull/9264 +.. _`#8556`: https://github.com/apache/cloudstack/pull/8556 +.. _`#9225`: https://github.com/apache/cloudstack/pull/9225 +.. _`#9435`: https://github.com/apache/cloudstack/pull/9435 +.. _`#8812`: https://github.com/apache/cloudstack/pull/8812 +.. _`#9396`: https://github.com/apache/cloudstack/pull/9396 +.. _`#9385`: https://github.com/apache/cloudstack/pull/9385 +.. _`#9201`: https://github.com/apache/cloudstack/pull/9201 +.. _`#9487`: https://github.com/apache/cloudstack/pull/9487 +.. _`#9499`: https://github.com/apache/cloudstack/pull/9499 +.. _`#9340`: https://github.com/apache/cloudstack/pull/9340 +.. _`#9390`: https://github.com/apache/cloudstack/pull/9390 +.. _`#9447`: https://github.com/apache/cloudstack/pull/9447 +.. _`#8615`: https://github.com/apache/cloudstack/pull/8615 +.. _`#9450`: https://github.com/apache/cloudstack/pull/9450 +.. _`#9426`: https://github.com/apache/cloudstack/pull/9426 +.. _`#9419`: https://github.com/apache/cloudstack/pull/9419 +.. _`#9399`: https://github.com/apache/cloudstack/pull/9399 +.. _`#9434`: https://github.com/apache/cloudstack/pull/9434 +.. _`#9458`: https://github.com/apache/cloudstack/pull/9458 +.. _`#9442`: https://github.com/apache/cloudstack/pull/9442 +.. _`#9437`: https://github.com/apache/cloudstack/pull/9437 +.. _`#8739`: https://github.com/apache/cloudstack/pull/8739 +.. _`#9043`: https://github.com/apache/cloudstack/pull/9043 +.. _`#9062`: https://github.com/apache/cloudstack/pull/9062 +.. _`#8833`: https://github.com/apache/cloudstack/pull/8833 +.. _`#9409`: https://github.com/apache/cloudstack/pull/9409 +.. _`#9402`: https://github.com/apache/cloudstack/pull/9402 diff --git a/source/releasenotes/compat.rst b/source/releasenotes/compat.rst index 7741da44ef..f40f6c0fae 100644 --- a/source/releasenotes/compat.rst +++ b/source/releasenotes/compat.rst @@ -22,45 +22,53 @@ Supported OS Versions for Management Server This section lists the operating systems that are supported for running CloudStack Management Server. -- Ubuntu 18.04 LTS, 20.04 LTS -- CentOS versions 7, 8 (note: CentOS 8 will EOL in Dec 2021) -- Rocky Linux 8 -- RHEL versions 7, 8 -- openSUSE Leap 15 -- SUSE Linux Enterprise Server 15 (not tested, but expected to work same as with openSUSE 15) +- Ubuntu 22.04 LTS, 24.04 LTS +- Oracle Linux 8, 9, 10 +- Rocky Linux 8, 9, 10 +- Alma Linux 8, 9, 10 +- RHEL versions 8, 9, 10 (not tested, but expected to work same as other EL distros) +- openSUSE Leap 15 (not widely tested and used by the community, tested to work openSUSE Leap 15.6) +- SUSE Linux Enterprise Server 15 (not tested, but expected to work same as with openSUSE 15 but likely require workarounds) +- Debian 12, 13 (not tested, but expected to work same as Ubuntu) - .. note:: There is a known issue with ipmitool with RHEL8 / SUSE, so certain functionality such as out of band management might not work + .. note:: There is a known issue with ipmitool with the EL and SUSE distros, so certain functionality such as out of band management might not work Software Requirements ~~~~~~~~~~~~~~~~~~~~~ -- Java JRE 11 -- MySQL 5.6, 5.7, 8.0 +- Java JRE 17 +- MySQL 8.0 (or equivalent compatible DBMS) Supported Hypervisor Versions ----------------------------- -CloudStack supports three hypervisor families, XenServer with XAPI, KVM, +CloudStack supports three hypervisor families, KVM, XenServer/XCP-ng with XAPI, and VMware with vSphere. -- Ubuntu 18.04 LTS, 20.04 LTS with KVM -- CentOS 7, 8 with KVM (note: CentOS 8 will EOL in Dec 2021) -- Rocky Linux 8 with KVM -- Red Hat Enterprise Linux 7, 8 with KVM -- Rocky Linux 8 with KVM -- openSUSE Leap 15 -- SUSE Linux Enterprise Server 15 -- XenServer versions 7.1, 7.2, 7.4, 7.5, 8.0 (8.1 and 8.2 expected to work, but not tested) with latest hotfixes, XCP-ng 7.4, 7.6, 8.0, 8.1, 8.2 +- Ubuntu 22.04 LTS, 24.04 LTS with KVM +- Oracle Linux 8, 9, 10 with KVM +- Rocky Linux 8, 9, 10 with KVM +- Alma Linux 8, 9, 10 with KVM +- RHEL 8, 9, 10 with KVM (not tested, but expected to work same as other EL distros) +- openSUSE Leap 15 with KVM (not widely tested and used by the community, tested to work openSUSE Leap 15.6) +- SUSE Linux Enterprise Server 15 with KVM (not tested, but expected to work same as with openSUSE 15 but likely require workarounds) +- XCP-ng 8.2.0 +- XCP-ng 8.3.0 +- Citrix Hypervisor/XenServer version 8.2 (not tested, but expected to work. For 8.2 please check the note below) with latest hotfixes +- Citrix Hypervisor/XenServer version 8.4 +- Debian 12, 13 with KVM (not tested, but expected to work same as Ubuntu) .. 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 `_. -- VMware versions 6.5, 6.7 and 7.0 + .. note:: For XenServer version 8.2 to work it might be necessary to manually add a custom storage repository with name "XenServer Tools" containing the systemvm.iso file. - .. 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. +- VMware versions 7.0 and 8.0.0 - .. note:: There is a known issue in 6.7 U3 - 6.7 U3f where a mailformed OVA could crash vCenter services (for more information see `here `_). To avoid the issue, make sure to use 6.7 U3g or later. + .. note:: The following VMware minor versions are supported and tested: 7.0, 7.0.1.0, 7.0.2.0, 7.0.3.0, 8.0, 8.0a (8.0.0.1), 8.0b (8.0.0.2), 8.0c (8.0.0.3), 8.0 U1 (8.0.1.0), 8.0 U2 (8.0.2.0), 8.0 U3 (8.0.3.0). + For any minor versions without hypervisor mappings, all Instances have guest OS identifier "otherGuest64" (x86-64 architecture) or "otherGuest" (other architectures). -- LXC Host Containers on RHEL 7 (not tested to work fine for last many CloudStack releases) + +- LXC Host Containers on RHEL 8, 9 (not tested to work fine for last many CloudStack releases) - Windows Server 2012 R2 with Hyper-V Role enabled (not tested to work fine for last many CloudStack releases) - Hyper-V 2012 R2 (not tested to work fine for last many CloudStack releases) - Oracle VM 3.0+ (not tested to work fine for last many CloudStack releases) @@ -70,7 +78,7 @@ and VMware with vSphere. - Fedora 17 - Ubuntu 12.04 -(not tested to work fine for last many CloudStack releases) +(not tested to work for last many CloudStack releases) Supported External Devices -------------------------- @@ -81,7 +89,6 @@ Supported External Devices - F5 11.X (not tested to work fine for last many CloudStack releases) - Force 10 Switch version S4810 for Baremetal Advanced Networks (not tested to work fine for last many CloudStack releases) - Supported Browsers ------------------ @@ -101,22 +108,20 @@ Notice Of Management OSes and Hypervisors to be Deprecated The following hypervisors are no longer be supported in this release due to vendor EOL: -- XenServer 6.2 -- XenServer 6.5 -- XenServer 7.0 -- vSphere 5.0 -- vSphere 5.1 -- vSphere 5.5 -- vSphere 6.0 -- CentOS/RHEL (KVM) 6.x -- Ubuntu 14.04 -- Ubuntu 16.04 +- KVM with CentOS/RHEL 6.x, 7.x +- KVM with CentOS 8.x +- KVM with Ubuntu 14.04, 16.04, 18.04 +- XCP-ng 7.4.0, 7.6.0, 8.0.0, 8.1.0 +- XenServer 6.2, 6.5, 7.0, 7.1, 7.2, 7.4, 7.5, 8.0, 8.1 +- vSphere 5.0, 5.1, 5.5, 6.0, 6.5, 6.7 The following Management Server Operating Systems are no longer supported in this release due to vendor EOL: -- CentOS 6.x -- Ubuntu 14.04 -- Ubuntu 16.04 +- CentOS/RHEL 6.x, 7.x +- CentOS 8.x [1]_ +- Ubuntu 14.04, 16.04, 18.04 + +.. [1] in spite of mostly being phased out some support is remaining in for now. See the section :ref:`Possible Issue with Guest OS IDs` for details. Please see `CloudStack Wiki `_ for details. diff --git a/source/releasenotes/locale/ja/LC_MESSAGES/about.po b/source/releasenotes/locale/ja/LC_MESSAGES/about.po index cadf46a936..028e8f5028 100644 --- a/source/releasenotes/locale/ja/LC_MESSAGES/about.po +++ b/source/releasenotes/locale/ja/LC_MESSAGES/about.po @@ -1158,7 +1158,7 @@ msgstr "" # 7497b1ecef6e4aa78d5fc1945d1552e6 #: ../../source/about.rst:589 msgid "" -"[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack failes with " +"[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack fails with " "time..." msgstr "" @@ -1533,7 +1533,7 @@ msgstr "" # d0f86a6e0cf344f6b651d4550e44c1e3 #: ../../source/about.rst:621 msgid "" -"A stopped vm cant start after disable threshold has been reached on the " +"A stopped vm can't start after disable threshold has been reached on the " "storage ..." msgstr "" diff --git a/source/releasenotes/locale/ja/LC_MESSAGES/rnotes.po b/source/releasenotes/locale/ja/LC_MESSAGES/rnotes.po index 7834db0880..4145386253 100644 --- a/source/releasenotes/locale/ja/LC_MESSAGES/rnotes.po +++ b/source/releasenotes/locale/ja/LC_MESSAGES/rnotes.po @@ -205,7 +205,7 @@ msgstr "" #: ../../source/rnotes.rst:1256 ../../source/rnotes.rst:1674 #: ../../source/rnotes.rst:2499 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-xen.vhd.bz2" msgstr "" @@ -426,7 +426,7 @@ msgstr "" #: ../../source/rnotes.rst:1281 ../../source/rnotes.rst:1700 #: ../../source/rnotes.rst:2524 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-kvm.qcow2.bz2" msgstr "" @@ -494,7 +494,7 @@ msgstr "" #: ../../source/rnotes.rst:1306 ../../source/rnotes.rst:1726 #: ../../source/rnotes.rst:2549 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-vmware.ova" msgstr "" @@ -2163,7 +2163,7 @@ msgstr "" msgid "" "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using " "the instructions in the `2.2.14 Release Notes " -"`__." +"`__." msgstr "" # 43af6a2f821148dc933817dda7004642 diff --git a/source/releasenotes/locale/pot/about.pot b/source/releasenotes/locale/pot/about.pot index 4d98216ced..dcf73dcc97 100644 --- a/source/releasenotes/locale/pot/about.pot +++ b/source/releasenotes/locale/pot/about.pot @@ -974,7 +974,7 @@ msgstr "" #: ../../about.rst:594 # ff5c9f0f0d034143be802c76448ed125 -msgid "[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack failes with time..." +msgid "[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack fails with time..." msgstr "" #: ../../about.rst:595 @@ -1294,7 +1294,7 @@ msgstr "" #: ../../about.rst:626 # d6831610409f4f188790c6d92247cb75 -msgid "A stopped vm cant start after disable threshold has been reached on the storage ..." +msgid "A stopped vm can't start after disable threshold has been reached on the storage ..." msgstr "" #: ../../about.rst:627 diff --git a/source/releasenotes/locale/pot/rnotes.pot b/source/releasenotes/locale/pot/rnotes.pot index 50a5d254a7..2ae491dec7 100644 --- a/source/releasenotes/locale/pot/rnotes.pot +++ b/source/releasenotes/locale/pot/rnotes.pot @@ -213,7 +213,7 @@ msgstr "" # a8b209e329fc41ce94ec334acd8dc4d0 # a26c20ade808412ab062e4a910efcde5 # bfaf491e156c4f9ab1e381a756900595 -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-xen.vhd.bz2" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-xen.vhd.bz2" msgstr "" #: ../../rnotes.rst:78 @@ -483,7 +483,7 @@ msgstr "" # b11d6d74b8e340d2af1246f535bed9e1 # 9ded492ee518410f88bfa49eab1e31b8 # 3fb14024946f4d70b472ccc0fa7b876a -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-kvm.qcow2.bz2" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-kvm.qcow2.bz2" msgstr "" #: ../../rnotes.rst:105 @@ -561,7 +561,7 @@ msgstr "" # c5214485e9114e2eb71127c7d7de6965 # 0c755ceff7c547348ff3a27a613ef83a # a56695f39bb84f899e7915122a3c430a -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-vmware.ova" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-vmware.ova" msgstr "" #: ../../rnotes.rst:130 @@ -2009,7 +2009,7 @@ msgstr "" #: ../../rnotes.rst:2456 # 0f112aff5e3a40229d261d3025697c2a -msgid "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the instructions in the `2.2.14 Release Notes `__." +msgid "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the instructions in the `2.2.14 Release Notes `__." msgstr "" #: ../../rnotes.rst:2460 diff --git a/source/upgrading/index.rst b/source/upgrading/index.rst index 9c4160ca3c..7a722f7dc1 100644 --- a/source/upgrading/index.rst +++ b/source/upgrading/index.rst @@ -28,11 +28,11 @@ Upgrading CloudStack This document contains the instructions for upgrading CloudStack from prior releases, to the current release. Please read through all sections carefully before starting. -From ACS 4.16 onwards, seeding of system-VM template is optional, as this will be taken care of by either the upgrade process or -in case of a fresh deployment, registration of the systemVM template(s) is handled during the addition of the first image store to a zone. -The `cloudstack-management` package will now include the systemVM templates for KVM, XenServer and VMWare. In case templates aren't already registered -either prior upgrade or during fresh installation, ACS will handle the template registration automatically, by mounting the secondary store onto the -management server, copying the respective templates to the store and then creating the `template.properties` file. +From ACS 4.16 onwards, seeding of system-VM Template is optional, as this will be taken care of by either the upgrade process or +in case of a fresh deployment, registration of the systemVM Template(s) is handled during the addition of the first image store to a zone. +The `cloudstack-management` package will now include the systemVM Templates for KVM, XenServer and VMWare. In case Templates aren't already registered +either prior upgrade or during fresh installation, ACS will handle the Template registration automatically, by mounting the secondary store onto the +management server, copying the respective Templates to the store and then creating the `template.properties` file. .. note:: For information on the API changes and issues fixed in this release, please see the Release Notes section of the documentation @@ -41,9 +41,17 @@ Contents: .. toctree:: :maxdepth: 1 - + + upgrade/upgrade_java_17_notes upgrade/mysql upgrade/valid_source + upgrade/upgrade-4.22 + upgrade/upgrade-4.21 + upgrade/upgrade-4.20 + upgrade/upgrade-4.19 + upgrade/upgrade-4.18 + upgrade/upgrade-4.17 + upgrade/upgrade-4.16 upgrade/upgrade-4.15 upgrade/upgrade-4.14 upgrade/upgrade-4.13 diff --git a/source/upgrading/locale/ja/LC_MESSAGES/about.po b/source/upgrading/locale/ja/LC_MESSAGES/about.po index cadf46a936..028e8f5028 100644 --- a/source/upgrading/locale/ja/LC_MESSAGES/about.po +++ b/source/upgrading/locale/ja/LC_MESSAGES/about.po @@ -1158,7 +1158,7 @@ msgstr "" # 7497b1ecef6e4aa78d5fc1945d1552e6 #: ../../source/about.rst:589 msgid "" -"[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack failes with " +"[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack fails with " "time..." msgstr "" @@ -1533,7 +1533,7 @@ msgstr "" # d0f86a6e0cf344f6b651d4550e44c1e3 #: ../../source/about.rst:621 msgid "" -"A stopped vm cant start after disable threshold has been reached on the " +"A stopped vm can't start after disable threshold has been reached on the " "storage ..." msgstr "" diff --git a/source/upgrading/locale/ja/LC_MESSAGES/rnotes.po b/source/upgrading/locale/ja/LC_MESSAGES/rnotes.po index 7834db0880..4145386253 100644 --- a/source/upgrading/locale/ja/LC_MESSAGES/rnotes.po +++ b/source/upgrading/locale/ja/LC_MESSAGES/rnotes.po @@ -205,7 +205,7 @@ msgstr "" #: ../../source/rnotes.rst:1256 ../../source/rnotes.rst:1674 #: ../../source/rnotes.rst:2499 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-xen.vhd.bz2" msgstr "" @@ -426,7 +426,7 @@ msgstr "" #: ../../source/rnotes.rst:1281 ../../source/rnotes.rst:1700 #: ../../source/rnotes.rst:2524 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-kvm.qcow2.bz2" msgstr "" @@ -494,7 +494,7 @@ msgstr "" #: ../../source/rnotes.rst:1306 ../../source/rnotes.rst:1726 #: ../../source/rnotes.rst:2549 msgid "" -"URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14" +"URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14" "-master-vmware.ova" msgstr "" @@ -2163,7 +2163,7 @@ msgstr "" msgid "" "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using " "the instructions in the `2.2.14 Release Notes " -"`__." +"`__." msgstr "" # 43af6a2f821148dc933817dda7004642 diff --git a/source/upgrading/locale/pot/about.pot b/source/upgrading/locale/pot/about.pot index 4d98216ced..dcf73dcc97 100644 --- a/source/upgrading/locale/pot/about.pot +++ b/source/upgrading/locale/pot/about.pot @@ -974,7 +974,7 @@ msgstr "" #: ../../about.rst:594 # ff5c9f0f0d034143be802c76448ed125 -msgid "[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack failes with time..." +msgid "[VMWARE] Cancel vCenter tasks if the task invoked by CloudStack fails with time..." msgstr "" #: ../../about.rst:595 @@ -1294,7 +1294,7 @@ msgstr "" #: ../../about.rst:626 # d6831610409f4f188790c6d92247cb75 -msgid "A stopped vm cant start after disable threshold has been reached on the storage ..." +msgid "A stopped vm can't start after disable threshold has been reached on the storage ..." msgstr "" #: ../../about.rst:627 diff --git a/source/upgrading/locale/pot/rnotes.pot b/source/upgrading/locale/pot/rnotes.pot index 50a5d254a7..2ae491dec7 100644 --- a/source/upgrading/locale/pot/rnotes.pot +++ b/source/upgrading/locale/pot/rnotes.pot @@ -213,7 +213,7 @@ msgstr "" # a8b209e329fc41ce94ec334acd8dc4d0 # a26c20ade808412ab062e4a910efcde5 # bfaf491e156c4f9ab1e381a756900595 -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-xen.vhd.bz2" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-xen.vhd.bz2" msgstr "" #: ../../rnotes.rst:78 @@ -483,7 +483,7 @@ msgstr "" # b11d6d74b8e340d2af1246f535bed9e1 # 9ded492ee518410f88bfa49eab1e31b8 # 3fb14024946f4d70b472ccc0fa7b876a -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-kvm.qcow2.bz2" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-kvm.qcow2.bz2" msgstr "" #: ../../rnotes.rst:105 @@ -561,7 +561,7 @@ msgstr "" # c5214485e9114e2eb71127c7d7de6965 # 0c755ceff7c547348ff3a27a613ef83a # a56695f39bb84f899e7915122a3c430a -msgid "URL: http://download.cloud.com/templates/4.3/systemvm64template-2014-01-14-master-vmware.ova" +msgid "URL: http://download.cloudstack.org/templates/4.3/systemvm64template-2014-01-14-master-vmware.ova" msgstr "" #: ../../rnotes.rst:130 @@ -2009,7 +2009,7 @@ msgstr "" #: ../../rnotes.rst:2456 # 0f112aff5e3a40229d261d3025697c2a -msgid "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the instructions in the `2.2.14 Release Notes `__." +msgid "If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the instructions in the `2.2.14 Release Notes `__." msgstr "" #: ../../rnotes.rst:2460 diff --git a/source/upgrading/upgrade/_java_version.rst b/source/upgrading/upgrade/_java_version.rst index 5604747836..860f619e2e 100644 --- a/source/upgrading/upgrade/_java_version.rst +++ b/source/upgrading/upgrade/_java_version.rst @@ -18,16 +18,16 @@ Java Version Requirement ------------------------ -CloudStack |version| requires installation of Java 11 JRE for management server +CloudStack |version| requires installation of Java 17 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 +cloudstack-agent packages, please configure Java 17 as the default java version using: .. parsed-literal:: $ sudo alternatives --config java -Note: For Ubuntu distributions where the openjdk-11 packages are not available +Note: For Ubuntu distributions where the openjdk-17 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: diff --git a/source/upgrading/upgrade/_log4j_file_check.rst b/source/upgrading/upgrade/_log4j_file_check.rst new file mode 100644 index 0000000000..28a22fd984 --- /dev/null +++ b/source/upgrading/upgrade/_log4j_file_check.rst @@ -0,0 +1,26 @@ +.. 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. + +.. note:: + + During upgrades from versions prior to 4.20, the logging configuration file may not be migrated automatically to the new Log4j2 format - especially if the original log4j configuration file was manually customized or modified. + + It is strongly recommended to verify **before starting the Management Server and the Usage Server** that the configuration file (e.g. `log4j-cloud.xml`) under `/etc/cloudstack/management` and `/etc/cloudstack/usage` respectively uses the Log4j2 format. + + If the file still uses legacy Log4j (version 1) syntax or structure, **manually replace or update** the configuration using the default Log4j2 configuration supplied with the latest package. + + Failure to update may result in missing or incomplete log generation after upgrade. diff --git a/source/upgrading/upgrade/_mysql_connector.rst b/source/upgrading/upgrade/_mysql_connector.rst index 77e03230f9..30e8beceaf 100644 --- a/source/upgrading/upgrade/_mysql_connector.rst +++ b/source/upgrading/upgrade/_mysql_connector.rst @@ -3,7 +3,7 @@ Install new MySQL connector Starting with 4.9.0, cloudstack-management RPM's now depend on the ``mysql-connector-python`` package. Therefore Apache CloudStack -|release| requires the instalation of the MySQL connector on CentOS. +|release| requires the installation of the MySQL connector on CentOS. MySQL connector RPM repository diff --git a/source/upgrading/upgrade/_no-sysvm_templates.rst b/source/upgrading/upgrade/_no-sysvm_templates.rst index dcfb81dc03..2034502345 100644 --- a/source/upgrading/upgrade/_no-sysvm_templates.rst +++ b/source/upgrading/upgrade/_no-sysvm_templates.rst @@ -15,7 +15,7 @@ .. sub-section included in upgrade notes. -Update System-VM templates +Update System VM Templates -------------------------- Upgrade from |version_to_upgrade| to |version| does not require new systemvm-templates. diff --git a/source/upgrading/upgrade/_sysvm_manual_hotfix.rst b/source/upgrading/upgrade/_sysvm_manual_hotfix.rst index 90a7d56fc3..da11ccd71c 100644 --- a/source/upgrading/upgrade/_sysvm_manual_hotfix.rst +++ b/source/upgrading/upgrade/_sysvm_manual_hotfix.rst @@ -13,10 +13,10 @@ specific language governing permissions and limitations under the License. -.. sub-section optinaly included in upgrade notes. +.. sub-section optionally included in upgrade notes. .. Add following to file when including this manual hotfix - .. _manual_hofix: + .. _manual_hotfix: Manual hotfix for systemvm upgrade ---------------------------------- @@ -26,13 +26,13 @@ Some manual steps are required to upgrade of SystemVMs and Virtual Routers. -Following MySQL commands will update the template ID used by Console Proxy VMs (CPVM) -and Secondary Storage VMs (SSVM). It will also change the default template for -Virtual Router to *systemvm--4.4* templates. +Following MySQL commands will update the Template ID used by Console Proxy VMs (CPVM) +and Secondary Storage VMs (SSVM). It will also change the default Template for +Virtual Router to *systemvm--4.4* Templates. -XenServer SystemVMs -^^^^^^^^^^^^^^^^^^^ +XenServer System VMs +^^^^^^^^^^^^^^^^^^^^ Execute following MySQL queries in MySQL. Please note ```` from the first command @@ -43,7 +43,7 @@ XenServer SystemVMs mysql -h localhost -u root -p cloud - #. get the id of the new template: + #. Get the id of the new Template: .. code-block:: mysql @@ -71,7 +71,7 @@ KVM SystemVMs mysql -h localhost -u root -p cloud - #. get the id of the new template: + #. Get the id of the new Template: .. code-block:: mysql @@ -99,7 +99,7 @@ VMware SystemVMs mysql -h localhost -u root -p cloud - #. get the id of the new template: + #. Get the id of the new Template: .. code-block:: mysql diff --git a/source/upgrading/upgrade/_sysvm_restart.rst b/source/upgrading/upgrade/_sysvm_restart.rst index 8f01fb2299..30f32282fb 100644 --- a/source/upgrading/upgrade/_sysvm_restart.rst +++ b/source/upgrading/upgrade/_sysvm_restart.rst @@ -15,9 +15,67 @@ .. sub-section included in upgrade notes. -Once you've upgraded the packages on your management servers, you'll +System VMs and Virtual Routers +------------------------------ + +From Apache CloudStack version 4.17.0 onward, there is support to live patch +System VMs, namely, SSVM, CPVM, Routers. Live patching provides support +for zero-downtime upgrades, wherein, the System VM software is updated to the +latest code version without having to destroy and recreate them / restart them. + +With this feature, users will have a choice wherein they can use the existing System VM Template with the latest +software by using the live patch feature, or can follow the usual workflow of restarting the +system VM to use the latest System VM Template. Live Patching System VMs serves to be especially +useful in cases when the code version has upgraded but the Template hasn't. In such a scenario users +will no longer need to restart the System VMs to use the latest code. + +When one attempts to live-patch the System VMs, it pretty much mimics the patching process +that happens when booting up the System VMs but without having to shut down the System VMs. +This will update the software packages, which were previously bundled in the systemvm.iso i.e., +agent.zip and cloud-scripts.tgz and restart the services that are present in the /var/cache/cloud/enabled_svcs file +in the System VMs. + +.. note:: + + The following services will be restarted once a system VM is live patched: + + +---------------------+-------------------------------+ + | **System VM** | **Services** | + +---------------------+-------------------------------+ + | SSVM | cloud, apache2, portmap | + +---------------------+-------------------------------+ + | CPVM | cloud | + +---------------------+-------------------------------+ + | VRs | haproxy, apache2, dnsmasq | + +---------------------+-------------------------------+ + + With respect to VRs, a Network restart without cleanup is initiated to during live patching to ensure all rules + are re-applied. + + **NOTE:** In cases where upgrading the system VM Template is necessary due to availability of security patches + or updated packages in the Template, or in case live-patch fails for system VMs and virtual routers due + to any issues or limitations (such as VPC Networks without any Network tiers) then please follow the + traditional method of upgrading system VMs and virtual routers by restarting or recreating the system VMs + and virtual routers (including restarting the Network with/without cleanup as required), which could mean + some downtime. + +Following matrix lists the versions of CloudStack that support live patching. + + +---------------------+-------------------------+--------------------------------+------------------------------------------+ + | **ACS Version** | **Upgrade Version** | **Live Patching Support** | **Reason / Comment** | + +---------------------+-------------------------+--------------------------------+------------------------------------------+ + | <=4.13 | 4.17+ | No | Update in the openJDK version | + +---------------------+-------------------------+--------------------------------+------------------------------------------+ + | 4.14 | 4.17+ |Yes | May notice some issue with remove access | + | | | | VPN due to older version of Strongswan | + +---------------------+-------------------------+--------------------------------+------------------------------------------+ + | >=4.15 | 4.17+ |Yes | N/A | + +---------------------+-------------------------+--------------------------------+------------------------------------------+ + +In addition to the support for live patching, users still have the facility to follow the legacy workflow +of restarting the system VMs once the packages on the management servers have been upgraded. Here you'll need to restart the system VMs in order for those VMs to be rebuilt -from the new systemVM template version. +from the new system VM Template version. .. note:: diff --git a/source/upgrading/upgrade/_sysvm_templates.rst b/source/upgrading/upgrade/_sysvm_templates.rst index 938d833b42..980d5f48a9 100644 --- a/source/upgrading/upgrade/_sysvm_templates.rst +++ b/source/upgrading/upgrade/_sysvm_templates.rst @@ -15,12 +15,12 @@ .. sub-section included in upgrade notes. -Update System-VM templates +Update System VM Templates -------------------------- .. note:: - From ACS 4.16 onwards, CloudStack will support automatic registration of systemVM - templates (when using noredist packages), if not done prior initiating upgrade. However, the usual upgrade process + From ACS 4.16 onwards, CloudStack will support automatic registration of System VM + Templates (when using noredist packages), if not done prior initiating upgrade. However, the usual upgrade process continues to be supported. #. While running the existing |version_to_upgrade| system, log in to the UI as @@ -30,12 +30,12 @@ Update System-VM templates #. In Select view, click Templates. -#. Click Register template. - The Register template dialog box is displayed. +#. Click Register Template. + The Register Template dialog box is displayed. -#. To register the system VM template do the following: +#. To register the System VM Template do the following: - In the Register template dialog box, specify the following values + In the Register Template dialog box, specify the following values (do not change these): .. cssclass:: table-striped table-bordered table-hover @@ -144,6 +144,6 @@ Update System-VM templates | | Routing: no | +------------+------------------------------------------------------------+ -#. Watch the screen to be sure that the template downloads successfully and +#. Watch the screen to be sure that the Template downloads successfully and enters the **READY** state. Do not proceed until this is successful. diff --git a/source/upgrading/upgrade/_sysvm_templates_pre45.rst b/source/upgrading/upgrade/_sysvm_templates_pre45.rst index 8f3ddfc093..9f3cb7fa02 100644 --- a/source/upgrading/upgrade/_sysvm_templates_pre45.rst +++ b/source/upgrading/upgrade/_sysvm_templates_pre45.rst @@ -15,11 +15,11 @@ .. sub-section included in upgrade notes. -Update System-VM templates +Update System-VM Templates -------------------------- .. warning:: - Upgrading from 4.4 or older to 4.6.0 require 2 systemvm templates to be + Upgrading from 4.4 or older to 4.6.0 require 2 systemvm Templates to be downloaded, for 4.5 and 4.6. #. While running the existing |version_to_upgrade| system, log in to the UI as @@ -29,13 +29,13 @@ Update System-VM templates #. In Select view, click Templates. -#. Register 4.5 systemvm template: +#. Register 4.5 systemvm Template: - #. Click Register template. + #. Click Register Template. - The Register template dialog box is displayed. + The Register Template dialog box is displayed. - #. In the Register template dialog box, specify the following values + #. In the Register Template dialog box, specify the following values (do not change these): .. cssclass:: table-striped table-bordered table-hover @@ -122,13 +122,13 @@ Update System-VM templates | | Routing: no | +------------+------------------------------------------------------------+ -#. Register |release| systemvm template: +#. Register |release| System VM Template: - #. Click Register template. + #. Click Register Template. - The Register template dialog box is displayed. + The Register Template dialog box is displayed. - #. In the Register template dialog box, specify the following values + #. In the Register Template dialog box, specify the following values (do not change these): .. cssclass:: table-striped table-bordered table-hover @@ -215,5 +215,5 @@ Update System-VM templates | | Routing: no | +------------+------------------------------------------------------------+ -#. Watch the screen to be sure that the template downloads successfully and +#. Watch the screen to be sure that the Template downloads successfully and enters the **READY** state. Do not proceed until this is successful. diff --git a/source/upgrading/upgrade/_xenserver_upg.rst b/source/upgrading/upgrade/_xenserver_upg.rst index 0440cfbff2..dc3a5a59a5 100644 --- a/source/upgrading/upgrade/_xenserver_upg.rst +++ b/source/upgrading/upgrade/_xenserver_upg.rst @@ -20,9 +20,9 @@ XenServer HA As of Apache CloudStack 4.4, CloudStack is not responsible to promote a new pool master on a Citrix XenServer pool. In case of failure of the pool master host, -the responsability of electing a new pool master as been delegated back to the +the responsibility of electing a new pool master as been delegated back to the HA feature of XenServer. CloudStack remain responsible to honored HA capability -for Compute Offerings of instances. The XenServer HA feature must be enabled +for Compute Offerings of Instances. The XenServer HA feature must be enabled only for the pool master, not for virtual-machines. diff --git a/source/upgrading/upgrade/mysql.rst b/source/upgrading/upgrade/mysql.rst index bbbc2d1ef6..c5aff07d39 100644 --- a/source/upgrading/upgrade/mysql.rst +++ b/source/upgrading/upgrade/mysql.rst @@ -18,13 +18,14 @@ MySQL upgrade problems With certain MySQL versions (see below), issues have been seen with "cloud.nics" table's column type (which was not updated properly during CloudStack upgrades, due to MySQL limitations), -which eventually may lead to exception seen in the management server logs, causing users to +which eventually may lead to exception seen in the management server logs, causing Users to not be able to start any VM. The following SQL statement needs to be manually executed in order to fix such issue: - .. parsed-literal:: -ALTER TABLE nics MODIFY COLUMN update_time timestamp DEFAULT CURRENT_TIMESTAMP; + .. code-block:: mysql + + ALTER TABLE nics MODIFY COLUMN update_time timestamp DEFAULT CURRENT_TIMESTAMP; The issue is known to affect the following MySQL server versions: diff --git a/source/upgrading/upgrade/upgrade-4.10.rst b/source/upgrading/upgrade/upgrade-4.10.rst index de1a2f5f8f..f0d63bd797 100644 --- a/source/upgrading/upgrade/upgrade-4.10.rst +++ b/source/upgrading/upgrade/upgrade-4.10.rst @@ -36,7 +36,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server @@ -53,8 +53,8 @@ http://markmail.org/message/f42kqr3mx4r4hgih .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -171,13 +171,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel410: @@ -362,7 +362,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -422,8 +423,6 @@ Restart management services .. parsed-literal:: $ sudo service cloudstack-usage start - -System-VMs and Virtual-Routers ------------------------------- + .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.11.rst b/source/upgrading/upgrade/upgrade-4.11.rst index da3dd27fc9..f18cb6b963 100644 --- a/source/upgrading/upgrade/upgrade-4.11.rst +++ b/source/upgrading/upgrade/upgrade-4.11.rst @@ -36,7 +36,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server @@ -50,8 +50,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -164,13 +164,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel411: @@ -256,7 +256,7 @@ Hypervisor: VMware build using "noredist". Refer to :ref:`building-noredist`. -No additional steps are requried for the VMware Hypervisor for this upgrade. +No additional steps are required for the VMware Hypervisor for this upgrade. .. _kvm411: @@ -284,7 +284,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Start the agent. @@ -303,7 +304,6 @@ For KVM hosts, upgrade the ``cloudstack-agent`` package .. parsed-literal:: $ sudo yum install -y epel-release - $ sudo yum install -y python36-libvirt $ sudo yum upgrade cloudstack-agent #. Restart the agent: @@ -329,7 +329,5 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.12.rst b/source/upgrading/upgrade/upgrade-4.12.rst index 75c6bc80e3..98ee5db6dc 100644 --- a/source/upgrading/upgrade/upgrade-4.12.rst +++ b/source/upgrading/upgrade/upgrade-4.12.rst @@ -35,7 +35,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server @@ -48,8 +48,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -163,13 +163,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel412: @@ -257,7 +257,7 @@ Hypervisor: VMware build using "noredist". Refer to :ref:`building-noredist`. -No additional steps are requried for the VMware Hypervisor for this upgrade. +No additional steps are required for the VMware Hypervisor for this upgrade. .. _kvm412: @@ -285,7 +285,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Start the agent. @@ -328,7 +329,5 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.13.rst b/source/upgrading/upgrade/upgrade-4.13.rst index 087437569e..687ae7c15b 100644 --- a/source/upgrading/upgrade/upgrade-4.13.rst +++ b/source/upgrading/upgrade/upgrade-4.13.rst @@ -36,7 +36,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. 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) @@ -51,8 +51,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -155,13 +155,13 @@ Setup the public key for the above repository: .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel413: @@ -235,7 +235,7 @@ Hypervisor: VMware built using "noredist". Refer to :ref:`building-noredist`. -No additional steps are requried for the VMware Hypervisor for this upgrade. +No additional steps are required for the VMware Hypervisor for this upgrade. .. _kvm413: @@ -263,7 +263,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Start the agent. @@ -282,7 +283,6 @@ For KVM hosts, upgrade the ``cloudstack-agent`` package .. parsed-literal:: $ sudo yum install -y epel-release - $ sudo yum install -y python36-libvirt $ sudo yum upgrade cloudstack-agent #. Restart the agent: @@ -308,7 +308,5 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.14.rst b/source/upgrading/upgrade/upgrade-4.14.rst index 7ea4ac6366..b830316bf0 100644 --- a/source/upgrading/upgrade/upgrade-4.14.rst +++ b/source/upgrading/upgrade/upgrade-4.14.rst @@ -36,7 +36,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server @@ -49,8 +49,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -149,13 +149,13 @@ Setup the public key for the above repository: .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel414: @@ -229,7 +229,7 @@ Hypervisor: VMware built using "noredist". Refer to :ref:`building-noredist`. -No additional steps are requried for the VMware Hypervisor for this upgrade. +No additional steps are required for the VMware Hypervisor for this upgrade. .. _kvm414: @@ -257,7 +257,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Start the agent. @@ -276,7 +277,6 @@ For KVM hosts, upgrade the ``cloudstack-agent`` package .. parsed-literal:: $ sudo yum install -y epel-release - $ sudo yum install -y python36-libvirt $ sudo yum upgrade cloudstack-agent #. Restart the agent: @@ -302,7 +302,5 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.15.rst b/source/upgrading/upgrade/upgrade-4.15.rst index 02ebdf9c22..e916e98075 100644 --- a/source/upgrading/upgrade/upgrade-4.15.rst +++ b/source/upgrading/upgrade/upgrade-4.15.rst @@ -36,7 +36,7 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server @@ -49,8 +49,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -150,13 +150,13 @@ Setup the public key for the above repository: .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel414: @@ -230,7 +230,7 @@ Hypervisor: VMware built using "noredist". Refer to :ref:`building-noredist`. -No additional steps are requried for the VMware Hypervisor for this upgrade. +No additional steps are required for the VMware Hypervisor for this upgrade. .. _kvm414: @@ -258,7 +258,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Start the agent. @@ -277,7 +278,6 @@ For KVM hosts, upgrade the ``cloudstack-agent`` package .. parsed-literal:: $ sudo yum install -y epel-release - $ sudo yum install -y python36-libvirt $ sudo yum upgrade cloudstack-agent #. Restart the agent: @@ -303,7 +303,5 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.16.rst b/source/upgrading/upgrade/upgrade-4.16.rst new file mode 100644 index 0000000000..208d8ffdf0 --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.16.rst @@ -0,0 +1,307 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.16.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM Template if not already using it. +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. warning:: + 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 + + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.17.rst b/source/upgrading/upgrade/upgrade-4.17.rst new file mode 100644 index 0000000000..ae58248a8a --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.17.rst @@ -0,0 +1,302 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.17.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM Template if not already using it. +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.18.rst b/source/upgrading/upgrade/upgrade-4.18.rst new file mode 100644 index 0000000000..61c910f5cb --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.18.rst @@ -0,0 +1,302 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.18.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM template if not already using it. +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.19.rst b/source/upgrading/upgrade/upgrade-4.19.rst new file mode 100644 index 0000000000..2addf4267a --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.19.rst @@ -0,0 +1,304 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.19.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM template if not already using it. +#. Confirm Java 17 is the default Java version +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + +.. include:: _java_version.rst + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.2.rst b/source/upgrading/upgrade/upgrade-4.2.rst index c76993b487..1aad550089 100644 --- a/source/upgrading/upgrade/upgrade-4.2.rst +++ b/source/upgrading/upgrade/upgrade-4.2.rst @@ -26,7 +26,7 @@ This section will guide you from CloudStack |version_to_upgrade| to CloudStack Upgrade Steps: -#. Install new System-VM templates +#. Install new System-VM Templates #. Backup CloudStack database (MySQL) @@ -149,13 +149,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel42: @@ -343,7 +343,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -422,7 +423,4 @@ values for ``mem.overporvisioning.factor`` and ``cpu.overporvisioning.factor``. .. _upg-sysvm42: -System-VMs and Virtual-Routers ------------------------------- - .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.20.rst b/source/upgrading/upgrade/upgrade-4.20.rst new file mode 100644 index 0000000000..dacf9a1ca6 --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.20.rst @@ -0,0 +1,305 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.20.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM template if not already using it. +#. Confirm Java 17 is the default Java version +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + +.. include:: _java_version.rst + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. include:: _log4j_file_check.rst + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.21.rst b/source/upgrading/upgrade/upgrade-4.21.rst new file mode 100644 index 0000000000..441990c851 --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.21.rst @@ -0,0 +1,305 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.21.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM template if not already using it. +#. Confirm Java 17 is the default Java version +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + +.. include:: _java_version.rst + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo service cloudstack-management stop + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo service cloudstack-usage stop + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 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: + + .. parsed-literal:: + + $ sudo apt-get update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. include:: _log4j_file_check.rst + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get upgrade cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo service cloudstack-agent start + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo service cloudstack-agent stop + $ sudo service cloudstack-agent start + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo service cloudstack-management start + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo service cloudstack-usage start + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.22.rst b/source/upgrading/upgrade/upgrade-4.22.rst new file mode 100644 index 0000000000..333fa2aaca --- /dev/null +++ b/source/upgrading/upgrade/upgrade-4.22.rst @@ -0,0 +1,314 @@ +.. 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. + +.. |version_to_upgrade| replace:: 4.22.x + +Upgrade Instruction from |version_to_upgrade| +============================================= + + +This section will show you how to upgrade from CloudStack |version_to_upgrade| to latest +CloudStack |release|. + +Any steps that are hypervisor-specific will be called out with a note. + +We recommend reading through this section once or twice before beginning +your upgrade procedure, and working through it on a test system before +working on a production system. + +.. note:: + The following upgrade instructions should be performed regardless of + hypervisor type. + +Overview of Upgrade Steps: +---------------------------- + +#. Check any customisations and integrations +#. Upload the |sysvm64-version| System VM template if not already using it. +#. Confirm Java 17 is the default Java version +#. Stop all running management servers +#. Backup CloudStack database (MySQL) +#. Upgrade 1st CloudStack management server +#. Update hypervisors specific dependencies +#. Restart 1st management server +#. Check that your upgraded environment works as expected +#. Upgrade and restart the remaining management servers + + +.. include:: _customisation_warnings.rst + +.. include:: _sysvm_templates.rst + +.. include:: _java_version.rst + +Packages repository +------------------- + +Most users of CloudStack manage the installation and upgrades of +CloudStack with one of Linux's predominant package systems, RPM or +APT. This guide assumes you'll be using RPM and Yum (for Red Hat +Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu). + +Create RPM or Debian packages (as appropriate) and a repository from +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:`ubuntu414` or :ref:`kvm414` hosts upgrade. + +Instructions for creating packages from the CloudStack source are in the +`CloudStack Installation Guide`_. + +Database Preparation +-------------------- + +Backup current database + +#. Stop your management server or servers. Run this on all management + server hosts: + + .. parsed-literal:: + + $ sudo systemctl stop cloudstack-management + +#. If you are running a usage server or usage servers, stop those as well: + + .. parsed-literal:: + + $ sudo systemctl stop cloudstack-usage + +#. Make a backup of your MySQL database. If you run into any issues or + need to roll back the upgrade, this will assist in debugging or + restoring your existing environment. You'll be prompted for your + password. + + .. parsed-literal:: + + $ mysqldump -u root -p -R cloud > cloud-backup_$(date +%Y-%m-%d-%H%M%S) + $ mysqldump -u root -p cloud_usage > cloud_usage-backup_$(date +%Y-%m-%d-%H%M%S) + +.. note:: + The -R option is required in the mysqldump command to retain MySQL stored procedures. + + +.. _ubuntu414: +.. _apt-repo414: + +Management Server +----------------- + +Ubuntu/Debian +###### + +If you are using Ubuntu, follow this procedure to upgrade your packages. If +not, skip to step :ref:`rhel414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + APT repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the sources list for +each system with CloudStack packages. This means all management +servers, and any hosts that have the KVM agent (no changes should +be necessary for hosts that are running VMware or Xen.) + +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 noble |version| + +If you are using Debian, + +.. parsed-literal:: + + deb http://download.cloudstack.org/debian bookworm |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: + + .. parsed-literal:: + + $ sudo apt update + +#. Now that you have the repository configured, it's time to upgrade + the ``cloudstack-management`` package. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-usage + + +.. _rhel414: +.. _rpm-repo414: + +CentOS/RHEL +############## + +If you are using CentOS or RHEL, follow this procedure to upgrade your +packages. If not, skip to hypervisors section :ref:`upg_hyp_414`. + +.. note:: + **Community Packages:** This section assumes you're using the community + supplied packages for CloudStack. If you've created your own packages and + yum repository, substitute your own URL for the ones used in these examples. + +The first order of business will be to change the yum repository +for each system with CloudStack packages. This means all +management servers, and any hosts that have the KVM agent (no changes +should be necessary for hosts that are running VMware or Xen.) + +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: + +.. parsed-literal:: + + [apache-cloudstack] + name=Apache CloudStack + baseurl=http://download.cloudstack.org/centos/$releasever/|version|/ + enabled=1 + gpgcheck=0 + +Setup the GPG public key if you wish to enable ``gpgcheck=1``: + +.. parsed-literal:: + + rpm --import http://download.cloudstack.org/RPM-GPG-KEY + +#. Now that you have the repository configured, it's time to upgrade the + ``cloudstack-management``. + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-management + +#. If you use CloudStack usage server + + .. parsed-literal:: + + $ sudo yum upgrade cloudstack-usage + +.. include:: _log4j_file_check.rst + +.. _upg_hyp_414: + +Upgrade Hypervisors +------------------- + +Hypervisor: XenServer +##################### + + +No additional steps are required for XenServer Hypervisor for this upgrade. + + +Hypervisor: VMware +################### + +.. warning:: + For VMware hypervisor, CloudStack management server packages must be + built using "noredist". Refer to :ref:`building-noredist`. + + +No additional steps are required for the VMware Hypervisor for this upgrade. + + +.. _kvm414: + +Hypervisor: KVM +################# + +KVM on Ubuntu/Debian +"""""""""""""" + +(KVM only) Additional steps are required for each KVM host. These +steps will not affect running guests in the cloud. These steps are +required only for clouds using KVM as hosts and only on the KVM +hosts. + +#. Configure the :ref:`APT repo ` as detailed above. + +#. Stop the running agent. + + .. parsed-literal:: + + $ sudo systemctl stop cloudstack-agent + +#. Update the agent software. + + .. parsed-literal:: + + $ sudo apt-get install cloudstack-agent + +#. Start the agent. + + .. parsed-literal:: + + $ sudo systemctl start cloudstack-agent + + +KVM on CentOS/RHEL +""""""""""""""""""" + +For KVM hosts, upgrade the ``cloudstack-agent`` package + +#. Configure the :ref:`rpm-repo414` as detailed above. + + .. parsed-literal:: + + $ sudo yum install -y epel-release + $ sudo yum upgrade cloudstack-agent + +#. Restart the agent: + + .. parsed-literal:: + + $ sudo systemctl stop cloudstack-agent + $ sudo systemctl start cloudstack-agent + + +Restart management services +--------------------------- + +#. Now it's time to start the management server + + .. parsed-literal:: + + $ sudo systemctl start cloudstack-management + +#. If you use it, start the usage server + + .. parsed-literal:: + + $ sudo systemctl start cloudstack-usage + + +.. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.3.rst b/source/upgrading/upgrade/upgrade-4.3.rst index f25cf218bb..cfec7a6f80 100644 --- a/source/upgrading/upgrade/upgrade-4.3.rst +++ b/source/upgrading/upgrade/upgrade-4.3.rst @@ -35,7 +35,7 @@ working on a production system. Upgrade Steps: #. Backup CloudStack database (MySQL) -#. Install new systemvm template +#. Install new systemvm Template #. Add package repository for MySQL connector #. Upgrade CloudStack management server(s) #. Update hypervisors specific dependencies @@ -154,13 +154,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel43: @@ -348,7 +348,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -412,7 +413,4 @@ Restart management services .. _upg-sysvm43: -System-VMs and Virtual-Routers ------------------------------- - .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.4.rst b/source/upgrading/upgrade/upgrade-4.4.rst index 47f0f33cc0..48e6ade3ff 100644 --- a/source/upgrading/upgrade/upgrade-4.4.rst +++ b/source/upgrading/upgrade/upgrade-4.4.rst @@ -35,7 +35,7 @@ working on a production system. Upgrade Steps: #. Backup CloudStack database (MySQL) -#. Install new systemvm template +#. Install new systemvm Template #. Add package repository for MySQL connector #. Upgrade CloudStack management server(s) #. Update hypervisors specific dependencies @@ -154,13 +154,13 @@ CloudStack apt repository .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel44: @@ -351,7 +351,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -425,7 +426,4 @@ Restart management services .. _upg-sysvm44: -System-VMs and Virtual-Routers ------------------------------- - .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.5.rst b/source/upgrading/upgrade/upgrade-4.5.rst index 2feea2f59b..adb913be19 100644 --- a/source/upgrading/upgrade/upgrade-4.5.rst +++ b/source/upgrading/upgrade/upgrade-4.5.rst @@ -35,7 +35,7 @@ working on a production system. Upgrade Steps: #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Add package repository for MySQL connector @@ -47,8 +47,8 @@ Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -166,13 +166,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel45: @@ -362,7 +362,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -425,8 +426,6 @@ Restart management services .. _upg-sysvm45: -System-VMs and Virtual-Routers ------------------------------- .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade-4.6.rst b/source/upgrading/upgrade/upgrade-4.6.rst index b7f951f8e0..d6bb437a1e 100644 --- a/source/upgrading/upgrade/upgrade-4.6.rst +++ b/source/upgrading/upgrade/upgrade-4.6.rst @@ -152,13 +152,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel46: @@ -348,7 +348,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: diff --git a/source/upgrading/upgrade/upgrade-4.7.rst b/source/upgrading/upgrade/upgrade-4.7.rst index c108e4792c..f22c02220e 100644 --- a/source/upgrading/upgrade/upgrade-4.7.rst +++ b/source/upgrading/upgrade/upgrade-4.7.rst @@ -151,13 +151,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel47: @@ -345,7 +345,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: diff --git a/source/upgrading/upgrade/upgrade-4.8.rst b/source/upgrading/upgrade/upgrade-4.8.rst index 64e05c45f9..4474fc1ad8 100644 --- a/source/upgrading/upgrade/upgrade-4.8.rst +++ b/source/upgrading/upgrade/upgrade-4.8.rst @@ -152,13 +152,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel48: @@ -348,7 +348,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: diff --git a/source/upgrading/upgrade/upgrade-4.9.rst b/source/upgrading/upgrade/upgrade-4.9.rst index eda121aceb..dba5270634 100644 --- a/source/upgrading/upgrade/upgrade-4.9.rst +++ b/source/upgrading/upgrade/upgrade-4.9.rst @@ -36,12 +36,12 @@ Overview of Upgrade Steps: ---------------------------- #. Check any customisations and integrations -#. Upload the |sysvm64-version| System VM template if not already using it. +#. Upload the |sysvm64-version| System VM Template if not already using it. #. Stop all running management servers #. Backup CloudStack database (MySQL) #. Upgrade 1st CloudStack management server #. Update hypervisors specific dependencies -#. Restart 1st management sserver +#. Restart 1st management server #. Check that your upgraded environment works as expected #. Upgrade and restart the remaining management servers @@ -50,8 +50,8 @@ Overview of Upgrade Steps: .. include:: _customisation_warnings.rst .. warning:: - 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 + 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 @@ -165,13 +165,13 @@ read as appropriate for your |version| repository. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-management + $ sudo apt-get install cloudstack-management #. If you use CloudStack usage server .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-usage + $ sudo apt-get install cloudstack-usage .. _rhel49: @@ -356,7 +356,8 @@ hosts. .. parsed-literal:: - $ sudo apt-get upgrade cloudstack-agent + $ sudo apt-get update + $ sudo apt-get install cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a line that reads: @@ -384,7 +385,6 @@ For KVM hosts, upgrade the ``cloudstack-agent`` package .. parsed-literal:: $ sudo yum install -y epel-release - $ sudo yum install -y python36-libvirt $ sudo yum upgrade cloudstack-agent #. Verify that the file ``/etc/cloudstack/agent/environment.properties`` has a @@ -420,7 +420,4 @@ Restart management services $ sudo service cloudstack-usage start -System-VMs and Virtual-Routers ------------------------------- - .. include:: _sysvm_restart.rst diff --git a/source/upgrading/upgrade/upgrade_java_17_notes.rst b/source/upgrading/upgrade/upgrade_java_17_notes.rst new file mode 100644 index 0000000000..a9a4c791f8 --- /dev/null +++ b/source/upgrading/upgrade/upgrade_java_17_notes.rst @@ -0,0 +1,43 @@ +.. 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 Release Notes documentation main file, created by + sphinx-quickstart on Fri Feb 7 16:00:59 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +|menu_acs_logo| + + +Upgrading CloudStack +==================== + +Java version upgraded to Java 17 +--------------------------------- + +As of Apache CloudStack 4.20, support for running with Java 17 has been added. +In later versions, support for Java 11 will be removed. + +If you are running CloudStack with Java 17, for CloudStack versions 4.20 and later: + * Verify /etc/default/cloudstack-management is consistent with https://github.com/apache/cloudstack/blob/main/packaging/systemd/cloudstack-management.default; Specifically, ensure that the following is present in the JAVA_OPTS: + + .. code-block:: bash + + --add-opens=java.base/java.lang=ALL-UNNAMED --add-exports=java.base/sun.security.x509=ALL-UNNAMED + + * Verify /etc/default/cloudstack-usage is also consistent with the same file in the repository. + * Perform the same check for /etc/default/cloudstack-agent on the hypervisor hosts. + +.. include:: _java_version.rst \ No newline at end of file diff --git a/source/upgrading/upgrade/upgrade_notes.rst b/source/upgrading/upgrade/upgrade_notes.rst deleted file mode 100644 index 7b2b7d1567..0000000000 --- a/source/upgrading/upgrade/upgrade_notes.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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. - - -General Upgrade Notes -===================== - - -Java version upgraded to Java 11 ---------------------------------- - -As of Apache CloudStack 4.14, Java version required is 11 for the -management-server, cloudstack-usage, KVM agent and system-VMs. - - -.. include:: _java_version.rst - -UI Deprecation and Removal Notice ---------------------------------- - -The current jQuery-based CloudStack UI is `deprecated -`_ in this release of CloudStack -and will be removed in the next release of Apache CloudStack. - -Migrating to dynamic roles feature ----------------------------------- - -As of Apache CloudStack 4.9, dynamic roles feature can be enabled after an -upgrade. Dyanamic roles feature is enabled by default on new installations. - -Please read more about :ref:`using-dynamics-roles` -feature and process of migrating to using this after an upgrade. - -Agent and KVM Host Security ---------------------------- - -Starting 4.11, a new CA framework has been introduced that is used to secure -agent and management server connections. Starting 4.11.1, KVM hosts in UP -state that are not secured (i.e. the KVM host agent and libvirtd don't have -CA framework provisioned X509 certificates) will show up as 'Unsecure'. A new -button in the UI is available as well as an API to secure and onboard such -hosts. - -Please read more about :ref:`host-security` and the process of migrating existing KVM hosts and agents to use the new security -feature. - -OVS plug-in ------------ - -OVS plug-in functionality is disrupted if ovsdaemon crashes - -A critical functionality issue came out with `CLOUDSTACK-6779 `_. On XenServer it -is observed that on VIF unplug Ovs-Vswitchd is crashing resulting in loosing all -the openflow rules added to the bridge. Ovs daemon gets started and creates a -bridge but configure openflow rules are lost resulting in the disruption of -connectivity for the VM's on the host. - - -Active-Directory Authentication (LDAP) --------------------------------------- - -If using Active-Directory (LDAP/LDAPs) as user authentication; Upgrading to -4.3 and later require changes in Global Settings. After upgrading CloudStack -to 4.3 or latest, following Global Settings must be change: - -.. cssclass:: table-striped table-bordered table-hover - -======================= ============== ============== -Global Settings Default New -======================= ============== ============== -ldap.user.object inetOrgPerson user -ldap.username.attribute uid sAMAccountName -======================= ============== ============== - - -SystemVM 32bit deprecated -------------------------- - -32bit versions of systemvm templates are in the process of behing deprecated. Upgrade instructions from this Release Notes use 64bit templates. - -Explicit JDBC driver declaration --------------------------------- - -While upgrading, on some environments the following may be required to be -added in CloudStack's db.properties file: - - # Add these to your db.properties file - - db.cloud.driver=jdbc:mysql - - db.usage.driver=jdbc:mysql - - -MySQL 8.0 sql mode change -------------------------- - -MySQL mode (sql_mode) has changed in CloudStack db.properties to -"STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, -ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION". - -This gets automatically applies to the MySQL session used by CloudStack management server. - -If the admin uses MySQL directly and wants to query tables it is advised to change the sql_mode in the corresponding session or globally. - -Eg. mysql> set global sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, - "> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"; - Query OK, 0 rows affected (0.00 sec) - - mysql> set sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, - "> ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"; - Query OK, 0 rows affected (0.00 sec) \ No newline at end of file