Unclear documentation how a complete minimal working configuration could look like for Ubuntu and Apache CloudStack

[Peter M.]

It's certainly clear that there are lots of possible configuration combinations (OSxProvider).

Initially, I have thought that picking up the relevant configuration by pieces would work, but then reading the manual leaves some uncertainties.

- information that you can place the configuration either in /etc/cloud/cloud.cfg or in /etc/cloud/cloud.cfg.d/* should be placed more prominently in an opening section, maybe also with an explained possible layout in the least. Are both ways idempotent, say, you could place everything in the single config file?

- for example for network configuration, the documentation https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html says "ethernets: []" is a valid default piece of configuration. Is it equivalent to using the "match" keyword with an asterisk?

- for CloudStack, is the data source configuration also a valid complete minimal configuration so that the machine is able to configure a default DHCP network and get metadata?

- debug: "verbose: true/false (defaulting to true)" does this mean, "verbose" is not needed but the "debug" statement has to be there to produce output?

- logging: "The default config is given as "output: { all: "| tee -a /var/log/cloud-init-output.log" }" - does it mean, for default logging I do not need to provide the "output" statement or exactly that is required to enabled it?

[Dan Watkins (oddbloke)]

Hi Peter,

Thanks for filing this bug! It's not entirely clear to me what you're trying to achieve here, which makes it difficult to help you. Could you clarify what you're trying to solve that's bringing up these issues? That will make it a lot easier to give you useful answers!

(Once you've done so, please move this back to New. :)

Thanks!

Dan

[Peter M. (jdoe666)]

Hi, Dan,

what I am trying to achieve: understand what is written in the documentation and apply it to create a VM template using relevant stances from the documentation. By bringing up these issues, I am trying to achieve that docuementation could be a) more clear b) contain complete working examples.

I will also file related and more specific issues shortly to give examples of the trial and error process coming from the fact that the documentation appears partly ambiguous to me as described above.

[Dan Watkins (oddbloke)]

> apply it to create a VM template

Most distros already have cloud-init packages that take care of a lot of this configuration. Have you checked if one exists for the distro you're working on?

> By bringing up these issues, I am trying to achieve that docuementation could be a) more clear b) contain complete working examples.

Our documentation could certainly use some improving, no doubt! Are you interested in contributing some improvements?

I'll see if I can address each of your points piecewise, now I have a better understanding of what you're doing.

> - information that you can place the configuration either in /etc/cloud/cloud.cfg or in /etc/cloud/cloud.cfg.d/* should be placed more prominently in an opening section, maybe also with an explained possible layout in the least.

Agreed.

> Are both ways idempotent, say, you could place everything in the single config file?

I'm not 100% sure I understand the way you're using "idempotent" here. That said, you can place everything in a single config file, yes. I believe the snippets in cloud.cfg.d will override the config in cloud.cfg (and later snippets in the .d directory will override earlier ones).

> - for example for network configuration, the documentation https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html

Network configuration is generally provided by the platform. In CloudStack's case, cloud-init doesn't have support for fetching network configuration from the platform. Where are you planning on putting this network configuration?

> says "ethernets: []" is a valid default piece of configuration. Is it equivalent to using the "match" keyword with an asterisk?

v2 network configuration (which you are referencing) is passed directly to netplan; you can see the full docs on it here: https://netplan.io/reference. An empty `ethernets` list is explicitly asking the system to configure _no_ ethernet interfaces, so it is not equivalent.

> - for CloudStack, is the data source configuration also a valid complete minimal configuration so that the machine is able to configure a default DHCP network and get metadata?

I would expect no specific configuration to be needed for the CloudStack data source to configure the first interface with DHCP.

> - debug: "verbose: true/false (defaulting to true)" does this mean, "verbose" is not needed but the "debug" statement has to be there to produce output?

cloud-init will produce non-debug output whether or not the debug stanza is present. You will need to enable cc_debug to see the debug output (which is why its default is to output), and you shouldn't need to specify any cc_debug configuration for it to be produced.

> - logging: "The default config is given as "output: { all: "| tee -a /var/log/cloud-init-output.log" }" - does it mean, for default logging I do not need to provide the "output" statement or exactly that is required to enabled it?

I believe that you don't need to provide the `output` statement to get logging. (Note that we would generally expect /var/log/cloud-init-output.log to be included in bug reports, so you may want to configure it regardless.)

Hope this helps!

Dan

[Peter M. (jdoe666)]

Hi, Dan,

thank you for your explanations; regarding contributing to the documentation, I think I will do so as soon as I am confident on a set of disambiguations and extensions to add.

So following from the explanations above, I consider that for a minimal working configuration to achieve that the guest tries to dial into the data source, the following will be enough (without line numbers):

========= /etc/cloud/cloud.cfg
 1 #cloud-config
 2 CloudStack:
 3 max_wait: 120
 4 timeout: 50
 5 datasource_list:
 6 - CloudStack

=========

To be sure regarding indentation, I've checked the file with yamllint and get only the following warnings:

  1:2 warning missing starting space in comment (comments)
  2:1 warning missing document start "---" (document-start)

So I expect that also without having Apache CloudStack in place, the cloud-init would be able to recognize this data source, configure network and try to dial into some DHCP.

For better reference, I've created a small project to share configuration files and scripts.
https://github.com/1605200517/cloud-init-debug/blob/master/ubuntu/config/18.04/etc/cloud/cloud.cfg

Though after the VM is booted, I still find cloud-init being disabled.

Please find attached the log dump. What I can see so far, the ds-identify script failed to determine the type of the data source and therefore it disables cloud-init.

kind regards
Peter

[Peter M. (jdoe666)]

An update.

Possibly, there is something wrong with the Ubuntu variant of cloud-init, because with an almost identical configuration for CentOS 8 on a local KVM the observation confirms the expectation: cloud-init automatically configures the network interface as expected, picks up CloudStack as data source and goes ahead for getting further data via DHCP.

https://github.com/1605200517/cloud-init-debug/blob/master/centos/config/8/etc/cloud/cloud.cfg

For a comparison, please find attached CentOS 8 logs.

[Dan Watkins (oddbloke)]

Hi Peter,

Thanks for the update! The Ubuntu logs answer the question of what the issue is: cloud-init does not detect that this is a CloudStack instance (or, indeed, an instance running on any cloud), so it disables itself. (The part of cloud-init that does this is called ds-identify, and you can see the output from it in /run/cloud-init/ds-identify.log in the tarball.)

The expectation that ds-identify has is that the DMI_PRODUCT_NAME on CloudStack instances will match "CloudStack*" (see [0] for the relevant code), whereas your platform is presenting "Standard PC (i440FX + PIIX, 1996)". So one route to addressing this would be to fix that in your CloudStack deployment.

Alternatively, you can ensure that you're specifying just one data source in your /etc/cloud/cloud.cfg (and cloud.cfg.d/*.cfg) configuration. I think you have a couple of barriers to that currently. Firstly, the default cloud-init installation will generate a /etc/cloud/cloud.cfg.d/90_dpkg.cfg file which enables all data sources[1], which would override your setting in cloud.cfg. Secondly, in your cloud.cfg, I _think_[2] that datasource_list is indented under the CloudStack stanza, when it should instead be top-level.

The best way of addressing this misconfiguration would be to configure cloud-init's deb packaging to only write out CloudStack into 90_dpkg.cfg. You can do this by hand with `dpkg-reconfigure cloud-init`. Does however you're building the images give you a way of supplying debconf selections? If so, I would use that to configure this.

So, to summarise: the best way to fix this would be to change the DMI product name that is presented to your instances, as that will ensure that unmodified installations of cloud-init (which, for example, your customers or users may perform in their own images) will function on your cloud. If you can't do that, then you need to ensure that the cloud.cfg configuration specifies only CloudStack as an option, as discussed above.

(Note that CentOS appears to work as you expect because it doesn't install the ds-identify component, so cloud-init is always enabled. However, it doesn't end up using the CloudStack data source.)

Thanks!

Dan

[0] https://github.com/canonical/cloud-init/blob/master/tools/ds-identify#L550-L554
[1] It does this because, in the general case, we want to consider all data sources when auto-detecting the platform we're on.
[2] Launchpad has unfortunately eaten the whitespace in your /etc/cloud/cloud.cfg, so I'm not 100% sure that this is correct. (It didn't eat it in my email notification, so this isn't a totally wild guess. :)

[Dan Watkins (oddbloke)]

(Moving this to Incomplete, please do move it back to New if there's still discussion to be had!)

[Launchpad Janitor (janitor)]

[Expired for cloud-init because there has been no activity for 60 days.]

[Scott Moser (smoser)]

Just to be clear. The expectation is that no special config is needed for cloud-init on CloudStack. It should "just work" with any version of cloudstack newer than 4.6 (4.6 was sometime in 2015, and the fix went in in July of 2015).

Additionally, Ubuntu images from cloud-images.ubuntu.com should "just work".

For reference, here are a related bugs:

https://bugs.launchpad.net/cloud-init/+bug/1674128
https://bugs.launchpad.net/cloud-init/+bug/1714358
https://issues.apache.org/jira/browse/CLOUDSTACK-8489

[James Falcon (falcojr)]

Tracked in Github Issues as https://github.com/canonical/cloud-init/issues/3513