reference.md

API reference

Each method's PHPDoc includes its complete signature, corresponding YAML key, and an @see reference to the official documentation. The lists below index implemented options; they do not imply support for every cloud-init module.

Parameter types describe what this library accepts. If the official schema supports additional forms, such as package versions or multiple sudo rules, that does not automatically extend the PHP signature. Omitted options follow image and cloud-init behavior; PHP argument defaults apply only when the corresponding method is called.

CloudInit / UserData

• hostname → CloudInit::setHostname().
• fqdn → CloudInit::setFqdn().
• timezone → CloudInit::setTimezone().
• locale → CloudInit::setLocale().
• preserve_hostname → CloudInit::setPreserveHostname().
• package_update → CloudInit::setPackageUpdate().
• package_upgrade → CloudInit::setPackageUpgrade().
• ssh_pwauth → CloudInit::setSshPasswordAuthentication().
• disable_root → CloudInit::setDisableRoot().
• ssh_authorized_keys → CloudInit::setSshKeys().
• ssh_authorized_keys → CloudInit::appendSshKeys().
• packages → CloudInit::setPackages().
• packages → CloudInit::appendPackages().
• packages → CloudInit::appendSudo() appends sudo.
• packages → CloudInit::appendCurlAndWget() appends curl and wget.
• packages → CloudInit::appendQemuGuestAgent() appends qemu-guest-agent.
• users[] → CloudInit::appendUser().
• write_files[] → CloudInit::appendFile().
• users[] = default → CloudInit::appendDefaultUser().
• runcmd[] → CloudInit::appendRunCommand().
• bootcmd[] → CloudInit::appendBootCommand().

User

• users[].name → User::make().
• users[].shell → User::setShell().
• users[].homedir → User::setHomeDirectory().
• users[].gecos → User::setGecos().
• users[].primary_group → User::setPrimaryGroup().
• users[].lock_passwd → User::setLockPassword().
• users[].sudo → User::setSudo().
• users[].groups → User::setGroups().
• users[].ssh_authorized_keys → User::setSshKeys().

File

• write_files[].path, write_files[].content → File::make().
• write_files[].content → File::setContent().
• write_files[].owner → File::setOwner().
• write_files[].permissions → File::setPermissions().
• write_files[].append → File::setAppend().
• write_files[].defer → File::setDefer().

For other options and modules, see the complete cloud-init reference.

MetaData

• instance-id → MetaData::setInstanceId().
• local-hostname → MetaData::setLocalHostname().

Reference: NoCloud.

NetworkConfig and Ethernet

• version: 2 → provided by NetworkConfig.
• ethernets.<id> → NetworkConfig::setEthernet() and Ethernet::make($id).
• dhcp4 / dhcp6 → Ethernet::setDhcp4() / setDhcp6().
• addresses → Ethernet::setAddresses().
• nameservers.addresses / nameservers.search → Ethernet::setNameservers() / setSearchDomains().
• match.macaddress / set-name → Ethernet::setMatchMacAddress() / setName().
• mtu → Ethernet::setMtu().
• routes[] → Ethernet::appendRoute().
• routes[].to / routes[].via → Route::make($to, $via).
• routes[].metric → Route::setMetric().

Reference: Network Version 2.

Platform-specific output

See the adapter option index for LXD configuration keys, the MAAS user_data parameter, and WSL filenames.

Chunk

UserData::chunk(MetaData $metaData, NetworkConfig $networkConfig): Chunk captures all three documents as rendered string snapshots. CloudInit inherits this method.

• Chunk::toArray() returns user-data, meta-data, and network-config strings.
• Chunk::renderString() returns one YAML mapping with literal document strings.
• Chunk::renderYaml($directory, $filename) writes the package using the usual output validation.
• Chunk::render() and string conversion also render the package.

Only the embedded user-data receives a #cloud-config header. Metadata and network validation still apply. The package is an application-level transport format; NoCloud requires the extracted documents as separate files. Later edits to source builders do not affect an existing chunk.

Exceptions

Exceptions live in the CloudInit\Exceptions namespace. Each validated field has a specific exception:

• Configuration: HostnameInvalidException, FqdnInvalidException, TimezoneInvalidException, and LocaleInvalidException.
• Lists: SshKeyInvalidException and PackageInvalidException, covering both list structure and individual entries.
• Users: UserNameInvalidException, ShellInvalidException, HomeDirectoryInvalidException, GecosInvalidException, GroupInvalidException, and SudoRuleInvalidException. User SSH keys also use SshKeyInvalidException.
• Configured files: FilePathInvalidException, FileOwnerInvalidException, and FilePermissionsInvalidException.
• Commands: CommandInvalidException.
• Metadata: InstanceIdInvalidException; the local hostname uses HostnameInvalidException.
• Networking: NetworkConfigInvalidException, NetworkInterfaceInvalidException, NetworkAddressInvalidException, NameserverInvalidException, NetworkRouteInvalidException, and NetworkMtuInvalidException.
• Datasource adapters: LxdConfigInvalidException and WslInstanceNameInvalidException.
• Output destinations: DirectoryInvalidException and FilenameInvalidException.

All the exceptions above extend ValidationException, which extends InvalidArgumentException. For example, SshKeyInvalidException identifies malformed lists or invalid entries without cryptographically validating a key.

Operational failures use FileWriteException or YamlRenderException, both extending RuntimeException. YamlRenderException preserves the original Symfony exception in getPrevious(). Native type errors remain TypeError.

use CloudInit\CloudInit;
use CloudInit\Exceptions\SshKeyInvalidException;
use CloudInit\Exceptions\ValidationException;
use CloudInit\Exceptions\FileWriteException;
use CloudInit\Exceptions\YamlRenderException;

try {
    CloudInit::make()
        ->appendSshKeys([''])
        ->renderYaml(__DIR__, 'user-data.yaml');
} catch (SshKeyInvalidException $exception) {
    // Handle the invalid SSH key list specifically.
} catch (ValidationException $exception) {
    // Handle any other builder validation failure.
} catch (FileWriteException | YamlRenderException $exception) {
    // Handle serialization or filesystem failures.
}