From 18008b6b63025f48a9cf44c421adf39974743620 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Mon, 7 Jun 2021 11:16:43 +0200 Subject: [PATCH 1/9] Cleanup --- source/adminguide/accounts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst index adc870fa4a..a7e699a97d 100644 --- a/source/adminguide/accounts.rst +++ b/source/adminguide/accounts.rst @@ -366,7 +366,7 @@ the user are used. #. CloudStack searches for it in LDAP by the configured ``ldap.username.attribute``. - #. If an LDAP user is found is found, CloudStack does a bind + #. If an LDAP user is found, CloudStack does a bind request with the returned principal for that LDAP user and the entered password. @@ -374,7 +374,7 @@ the user are used. 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. From 16f5e5f72a7b83f370ee518a34c7705cb2a30546 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Mon, 28 Jun 2021 09:41:47 +0200 Subject: [PATCH 2/9] Updated networking and added config drive --- source/adminguide/api.rst | 93 ++++++++++++++++++- .../networking/advanced_zone_config.rst | 25 +++-- 2 files changed, 106 insertions(+), 12 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index 75df8a1f82..3fe5b34589 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -43,8 +43,8 @@ possible as well. For example, see Using an LDAP Server for User Authentication. -User Data and Meta Data ------------------------ +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 @@ -87,4 +87,93 @@ is also supported.) For metadata type, use one of the following: - instance-id. The instance name of the VM +User Data and Meta Data via Config Drive +---------------------------------------- +The user-data service on a Shared or L2 Network can be provided through the +Virtual Router or through an attached iso called the 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 +password files. + +Enable config drive +~~~~~~~~~~~~~~~~~~~ +To use the config drive the network offering must have the “ConfigDrive” +provider selected for the userdata service. + +If the networkoffering uses ConfigDrive for userdata and the template is +password enabled, the password string for the VM is placed in 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) +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, Secondary Storage VM will rebuild the +ConfigDrive ISO image. That is the existing ISO is mounted on a temporary directory, +password, userdata 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. + +When a VM is stopped, the ConfigDrive network element will trigger the +Secondary Storage VM to remove the ISO from the secondary storage. + +Since the ISO is available on secondary storage, there is no need for an extra +implementation in case of migration. + +Supporting ConfigDrive +~~~~~~~~~~~~~~~~~~~~~~ + +Extra data is added to the VM profile to enable the creation of the config drive: + +VMdata - a list of String arrays representing [“directory”, “filename”, “content”] on the ConfigDrive device. + +- /cloudstack + + - /metadata: + + - availability-zone.txt + + - instance-id.txt + + - service-offering.txt + + - cloud-identifier.txt + + - local-hostname.txt + + - vm-id.txt + + - public-keys.txt + + - /password + + - vm_password.txt + + - vm_password_md5checksum (for windows VM’s) + +- /openstack/version/: + + - user_data (=hardlink to /cloudstack/user_data/user_data.txt) + + - vendor_data.json + + - meta_data.json + + - Network_data.json + + - label, which is configurable in global settings: + + - name : vm.configdrive.label + + - default: config-2 + +For more detailed information about the Config Drive implementation refer to +the `Wiki Article +`_ \ No newline at end of file diff --git a/source/adminguide/networking/advanced_zone_config.rst b/source/adminguide/networking/advanced_zone_config.rst index 6ada489501..f36fc0dcd2 100644 --- a/source/adminguide/networking/advanced_zone_config.rst +++ b/source/adminguide/networking/advanced_zone_config.rst @@ -29,22 +29,20 @@ 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: -#. In the left navigation, choose Infrastructure. On Zones, click View - More, then click the zone to which you want to add a network. +#. In the left navigation, choose Network. -#. Click the Network tab. - -#. Click Add guest network. +#. Click Add network. The Add guest network window is displayed: |addguestnetwork.png| -#. Provide the following information: +#. Provide the following information for creating an isolated network: - **Name**: The name of the network. This will be user-visible + + - **Description**: The description of the network. This will be - - **Display Text**: The description of the network. This will be user-visible - **Zone**: The zone in which you are configuring the guest network. @@ -52,10 +50,17 @@ configure the base guest network: - **Network offering**: If the administrator has configured multiple network offerings, select the one you want to use for this network - - **Guest Gateway**: The gateway that the guests should use + - **External Id**: ID of the network in an external system. + + - **Gateway**: The gateway that the guests instances will use. + + - **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 + DNS suffix. - - **Guest Netmask**: The netmask in use on the subnet the guests - will use #. Click OK. From 7579dc01db266473377e80c7f35c2b28770a5c22 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Wed, 30 Jun 2021 20:25:16 +0200 Subject: [PATCH 3/9] Renamed password file name --- source/adminguide/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index 3fe5b34589..c0be62e87f 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -103,8 +103,8 @@ To use the config drive the network offering must have the “ConfigDrive” provider selected for the userdata service. If the networkoffering uses ConfigDrive for userdata and the template is -password enabled, the password string for the VM is placed in password.txt file -and it is included in the ISO. +password enabled, the password string for the VM is placed in the +vm_password.txt file and it is included in the ISO. ConfigDrive availability ~~~~~~~~~~~~~~~~~~~~~~~~ From 488ac8d49f969f5764380c834ba9c9f462b48513 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Wed, 30 Jun 2021 20:30:20 +0200 Subject: [PATCH 4/9] Changed L2 networks title --- source/adminguide/networking.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/adminguide/networking.rst b/source/adminguide/networking.rst index 6bd739a259..75306d23cd 100644 --- a/source/adminguide/networking.rst +++ b/source/adminguide/networking.rst @@ -88,8 +88,8 @@ Basic zones or Advanced Zones with Security Groups. Network” `_. -L2 Networks -~~~~~~~~~~~ +L2 (Layer 2) Networks +~~~~~~~~~~~~~~~~~~~~~ L2 networks provide network isolation without any other services. This means that there will be no virtual router. It is assumed that the end From bd9c61018a3bdae5ed621c8a1e3256322811925e Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Fri, 2 Jul 2021 10:03:40 +0200 Subject: [PATCH 5/9] Changed headings --- source/adminguide/api.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index c0be62e87f..c0fe5be663 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -43,8 +43,11 @@ possible as well. For example, see Using an LDAP Server for User Authentication. -User Data and Meta Data via Virtual Router ------------------------------------------- +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 @@ -87,8 +90,8 @@ is also supported.) For metadata type, use one of the following: - instance-id. The instance name of the VM -User Data and Meta Data via Config Drive ----------------------------------------- +Via Config Drive +~~~~~~~~~~~~~~~~ The user-data service on a Shared or L2 Network can be provided through the Virtual Router or through an attached iso called the Config drive. From b934dbcc46fde510eb79e1617decea7d10dd7356 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Sun, 4 Jul 2021 08:09:50 +0200 Subject: [PATCH 6/9] Review changes to config drive --- source/adminguide/api.rst | 61 ++++----------------------------------- 1 file changed, 6 insertions(+), 55 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index c0fe5be663..649f140645 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -43,58 +43,8 @@ possible as well. For example, see Using an LDAP Server for User Authentication. -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 -virtual router. - -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: - -#. 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 - 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 - -- availability-zone. The Zone name - -- local-ipv4. The guest IP of the VM - -- local-hostname. The hostname of the VM - -- 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 - -Via Config Drive -~~~~~~~~~~~~~~~~ - -The user-data service on a Shared or L2 Network can be provided through the -Virtual Router or through an attached iso called the Config drive. +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 @@ -116,7 +66,7 @@ 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, Secondary Storage VM will rebuild the +At password reset or update of user data, Secondary Storage VM will rebuild the ConfigDrive ISO image. That is the existing ISO is mounted on a temporary directory, password, userdata or ssh-keys are updated and a new ISO is built from the updated directory structure. @@ -127,8 +77,9 @@ To access the updated userdata, the user needs to remount the config drive ISO. When a VM is stopped, the ConfigDrive network element will trigger the Secondary Storage VM to remove the ISO from the secondary storage. -Since the ISO is available on secondary storage, there is no need for an extra -implementation in case of migration. +The config drive ISO can be stored on primary storage by setting the global +setting vm.configdrive.primarypool.enabled to true. This is currently only +supported with use of the KVM Hypervisor. Supporting ConfigDrive ~~~~~~~~~~~~~~~~~~~~~~ From 913576e7f6a573b5d6c0ef07ca6c8baf4c37735a Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Mon, 5 Jul 2021 10:47:41 +0200 Subject: [PATCH 7/9] Replaced missing section --- source/adminguide/api.rst | 46 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index 649f140645..30838ce3e9 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -43,6 +43,52 @@ possible as well. For example, see Using an LDAP Server for User Authentication. +User Data and Meta Data +~~~~~~~~~~~~~~~~~~~~~~~ + +The user-data service on a Shared or L2 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 +virtual router. + +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: + +#. 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 + 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 + +- availability-zone. The Zone name + +- local-ipv4. The guest IP of the VM + +- local-hostname. The hostname of the VM + +- 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 + User Data and Meta Data via Config Drive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From aa782648d2edc77923be9ce160191849e2150707 Mon Sep 17 00:00:00 2001 From: spaceman1984 Date: Mon, 5 Jul 2021 11:28:48 +0200 Subject: [PATCH 8/9] Added change to storage --- source/adminguide/api.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index 30838ce3e9..9ec138eb02 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -112,8 +112,8 @@ 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, Secondary Storage VM will rebuild the -ConfigDrive ISO image. That is the existing ISO is mounted on a temporary directory, +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 updated directory structure. @@ -122,6 +122,8 @@ To access the updated userdata, the user needs to remount the config drive ISO. When a VM 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. The config drive ISO can be stored on primary storage by setting the global setting vm.configdrive.primarypool.enabled to true. This is currently only From ac12d4fbdd0187cb877131508128a18287605051 Mon Sep 17 00:00:00 2001 From: Andrija Panic <45762285+andrijapanicsb@users.noreply.github.com> Date: Mon, 4 Oct 2021 13:31:03 +0200 Subject: [PATCH 9/9] Update api.rst --- source/adminguide/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/adminguide/api.rst b/source/adminguide/api.rst index 9ec138eb02..db40d5f4db 100644 --- a/source/adminguide/api.rst +++ b/source/adminguide/api.rst @@ -46,7 +46,7 @@ Authentication. User Data and Meta Data ~~~~~~~~~~~~~~~~~~~~~~~ -The user-data service on a Shared or L2 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 @@ -178,4 +178,4 @@ VMdata - a list of String arrays representing [“directory”, “filename”, For more detailed information about the Config Drive implementation refer to the `Wiki Article -`_ \ No newline at end of file +`_