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/README.rst b/README.rst index ab53a625df..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. 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/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/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/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/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/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/adminguide/accounts.rst b/source/adminguide/accounts.rst index e23d9fe6e1..b70515c0e9 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -49,6 +49,8 @@ Beside the Root Administrator type of Account (available in the root domain only of Accounts can be created for each domain: Domain Administrator and User. +.. _users: + Users ~~~~~ @@ -901,6 +903,124 @@ password for a user: .. 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. diff --git a/source/adminguide/hosts.rst b/source/adminguide/hosts.rst index 87d5d94544..b7c6b8df43 100644 --- a/source/adminguide/hosts.rst +++ b/source/adminguide/hosts.rst @@ -770,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 @@ -780,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 @@ -806,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 -------------------- diff --git a/source/adminguide/networking/site_to_site_vpn.rst b/source/adminguide/networking/site_to_site_vpn.rst index 29aeea7962..7bf09767ae 100644 --- a/source/adminguide/networking/site_to_site_vpn.rst +++ b/source/adminguide/networking/site_to_site_vpn.rst @@ -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. @@ -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>`_. @@ -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/virtual_private_cloud_config.rst b/source/adminguide/networking/virtual_private_cloud_config.rst index 219f4ea7f4..2a2bb57dd4 100644 --- a/source/adminguide/networking/virtual_private_cloud_config.rst +++ b/source/adminguide/networking/virtual_private_cloud_config.rst @@ -210,6 +210,19 @@ addresses in the form of a Classless Inter-Domain Routing (CIDR) block. - **VPC Offering**: If the administrator has configured multiple 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. diff --git a/source/adminguide/service_offerings.rst b/source/adminguide/service_offerings.rst index bd76e31ceb..f8d0eacce3 100644 --- a/source/adminguide/service_offerings.rst +++ b/source/adminguide/service_offerings.rst @@ -19,6 +19,9 @@ .. |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 @@ -655,6 +658,19 @@ 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 ------------------ diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst index 7a035485da..ec0e00d298 100644 --- a/source/adminguide/systemvm.rst +++ b/source/adminguide/systemvm.rst @@ -76,11 +76,20 @@ 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. -ARM 64-bit template(s) will be downloaded from the official repository -and the same workflow for the registration and seeding will be used. If -the automatic download and seeding of ARM 64-bit template fails, the -template can be manually registered in a multi-architecture zone or -will need manual registration and seeding in a ARM 64-bit only zone. +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 diff --git a/source/adminguide/virtual_machines.rst b/source/adminguide/virtual_machines.rst index 0e463b9661..3a07f40a89 100644 --- a/source/adminguide/virtual_machines.rst +++ b/source/adminguide/virtual_machines.rst @@ -1190,9 +1190,8 @@ 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. - -|vm-settings-virtual-tpm-model-kvm.png| -TPM model for KVM. There are two options: +- 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. diff --git a/source/installguide/management-server/_database.rst b/source/installguide/management-server/_database.rst index 1e626dafaf..c1eec4ef37 100644 --- a/source/installguide/management-server/_database.rst +++ b/source/installguide/management-server/_database.rst @@ -286,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: @@ -518,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/plugins/cloudstack-kubernetes-service.rst b/source/plugins/cloudstack-kubernetes-service.rst index 0682162359..12921f30f2 100644 --- a/source/plugins/cloudstack-kubernetes-service.rst +++ b/source/plugins/cloudstack-kubernetes-service.rst @@ -653,6 +653,45 @@ Administrators are able to dedicate hosts to a domain or account. CloudStack wil .. 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -809,6 +848,8 @@ kubectl delete pod --all -A :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 diff --git a/source/quickinstallationguide/qig.rst b/source/quickinstallationguide/qig.rst index 02e346a9a2..5cfdab03bf 100644 --- a/source/quickinstallationguide/qig.rst +++ b/source/quickinstallationguide/qig.rst @@ -402,23 +402,46 @@ up the management server by issuing the following command: # cloudstack-setup-management - -System Template Setup -~~~~~~~~~~~~~~~~~~~~~ - -CloudStack uses a number of system VMs to provide functionality for accessing -the console of Instances, providing various networking services, and -managing various aspects of storage. - -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 following script: + .. note:: + Since 4.23.0, the ``cloudstack-setup-management`` command + can download SystemVM 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. + + +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| \