Documentation

Overview

    Package cloudinit implements a way of creating a cloud-init configuration file. See https://help.ubuntu.com/community/CloudInit.

    Index

    Constants

    View Source
    const CloudInitNetworkConfigDisabled = `config: "disabled"
    `
    View Source
    const NetworkInterfacesScript = `` /* 3417-byte string literal not displayed */
    

    Variables

    This section is empty.

    Functions

    func GenerateENITemplate

    func GenerateENITemplate(interfaces corenetwork.InterfaceInfos) (string, error)

      GenerateENITemplate renders an e/n/i template config for one or more network interfaces, using the given non-empty interfaces list.

      func GenerateNetplan

      func GenerateNetplan(interfaces corenetwork.InterfaceInfos) (string, error)

        GenerateNetplan renders a netplan file for one or more network interfaces, using the given non-empty list of interfaces.

        func InitProgressCmd

        func InitProgressCmd() string

          InitProgressCmd will return a command to initialise progress reporting, sending messages to stderr. If LogProgressCmd is used in a script, InitProgressCmd MUST be executed beforehand.

          The returned commands are idempotent; this is important, to allow a script to be embedded in another with stderr redirected, in which case InitProgressCmd must precede the redirection.

          func LogProgressCmd

          func LogProgressCmd(format string, args ...interface{}) string

            LogProgressCmd will return a command to log the specified progress message to stderr; the resultant command should be added to the configuration as a runcmd or bootcmd as appropriate.

            If there are any uses of LogProgressCmd in a configuration, the configuration MUST precede the command with the result of InitProgressCmd.

            Types

            type AdvancedPackagingConfig

            type AdvancedPackagingConfig interface {
            	// Adds the necessary commands for installing the required packages for
            	// each OS is they are necessary.
            	AddPackageCommands(
            		proxyCfg PackageManagerProxyConfig,
            		addUpdateScripts bool,
            		addUpgradeScripts bool,
            	) error
            
            	// RequiresCloudArchiveCloudTools determines whether the cloudconfig
            	// requires the configuration of the cloud archive depending on its series.
            	RequiresCloudArchiveCloudTools() bool
            
            	// AddCloudArchiveCloudTools configures the cloudconfig to set up the cloud
            	// archive if it is required (eg: LTS'es).
            	AddCloudArchiveCloudTools()
            	// contains filtered or unexported methods
            }

              Makes two more advanced package commands available

              type BootCmdsConfig

              type BootCmdsConfig interface {
              	// AddBootCmd adds a command to be executed on *every* boot.
              	// It can receive any number of string arguments, which will be joined into
              	// a single command.
              	// NOTE: metacharecters will not be escaped.
              	AddBootCmd(...string)
              
              	// RemoveBootCmd removes the given command from the list of commands to be
              	// run every boot. If it has not been previously added, no error occurs.
              	RemoveBootCmd(string)
              
              	// BootCmds returns all the commands added with AddBootCmd.
              	BootCmds() []string
              }

                BootCmdsConfig is the interface for all operations on early-boot commands.

                type CloudConfig

                type CloudConfig interface {
                	// SetAttr sets an arbitrary attribute in the cloudinit config.
                	// The value will be marshalled according to the rules
                	// of the goyaml.Marshal.
                	SetAttr(string, interface{})
                
                	// UnsetAttr unsets the attribute given from the cloudinit config.
                	// If the attribute has not been previously set, no error occurs.
                	UnsetAttr(string)
                
                	// GetSeries returns the series this CloudConfig was made for.
                	GetSeries() string
                
                	// CloudConfig also contains all the smaller interfaces for config
                	// management:
                	UsersConfig
                	SystemUpdateConfig
                	SystemUpgradeConfig
                	PackageProxyConfig
                	PackageMirrorConfig
                	PackageSourcesConfig
                	PackagingConfig
                	RunCmdsConfig
                	BootCmdsConfig
                	EC2MetadataConfig
                	FinalMessageConfig
                	LocaleConfig
                	DeviceMountConfig
                	OutputConfig
                	SSHAuthorizedKeysConfig
                	SSHKeysConfig
                	RootUserConfig
                	WrittenFilesConfig
                	RenderConfig
                	AdvancedPackagingConfig
                	HostnameConfig
                	NetworkingConfig
                }

                  CloudConfig is the interface of all cloud-init cloudconfig options.

                  func New

                  func New(ser string) (CloudConfig, error)

                    New returns a new Config with no options set.

                    type DeviceMountConfig

                    type DeviceMountConfig interface {
                    	// AddMount adds takes arguments for installing a mount point in /etc/fstab
                    	// The options are of the order and format specific to fstab entries:
                    	// <device> <mountpoint> <filesystem> <options> <backup setting> <fsck priority>
                    	AddMount(...string)
                    }

                      DeviceMountConfig is the interface for all device mounting settings.

                      type EC2MetadataConfig

                      type EC2MetadataConfig interface {
                      	// SetDisableEC2Metadata sets whether access to the EC2 metadata service is
                      	// disabled early in boot via a null route. The default value is false.
                      	// (route del -host 169.254.169.254 reject).
                      	SetDisableEC2Metadata(bool)
                      
                      	// UnsetDisableEC2Metadata unsets the value set by SetDisableEC2Metadata,
                      	// returning it to the cloudinit-defined value of false.
                      	// If the option has not been previously set, no error occurs.
                      	UnsetDisableEC2Metadata()
                      
                      	// DisableEC2Metadata returns the value set by SetDisableEC2Metadata or
                      	// false if it has not been previously set.
                      	DisableEC2Metadata() bool
                      }

                        EC2MetadataConfig is the interface for all EC2-metadata related settings.

                        type FinalMessageConfig

                        type FinalMessageConfig interface {
                        	// SetFinalMessage sets to message that will be written when the system has
                        	// finished booting for the first time. By default, the message is:
                        	// "cloud-init boot finished at $TIMESTAMP. Up $UPTIME seconds".
                        	SetFinalMessage(string)
                        
                        	// UnsetFinalMessage unsets the value set by SetFinalMessage.
                        	// If it has not been previously set, no error occurs.
                        	UnsetFinalMessage()
                        
                        	// FinalMessage returns the value set using SetFinalMessage or an empty
                        	// string if it has not previously been set.
                        	FinalMessage() string
                        }

                          FinalMessageConfig is the interface for all settings related to the cloudinit final message.

                          type HostnameConfig

                          type HostnameConfig interface {
                          	// ManageEtcHosts enables or disables management of /etc/hosts.
                          	ManageEtcHosts(manage bool)
                          }

                            HostnameConfig is the interface for managing the hostname.

                            type LocaleConfig

                            type LocaleConfig interface {
                            	// SetLocale sets the locale; it defaults to en_US.UTF-8
                            	SetLocale(string)
                            
                            	// UnsetLocale unsets the option set by SetLocale, returning it to the
                            	// cloudinit-defined default of en_US.UTF-8
                            	// If it has not been previously set, no error occurs
                            	UnsetLocale()
                            
                            	// Locale returns the locale set with SetLocale
                            	// If it has not been previously set, an empty string is returned
                            	Locale() string
                            }

                              LocaleConfig is the interface for all locale-related setting operations.

                              type NetworkingConfig

                              type NetworkingConfig interface {
                              	// AddNetworkConfig adds network config from interfaces to the container.
                              	AddNetworkConfig(interfaces corenetwork.InterfaceInfos) error
                              }

                                NetworkingConfig is the interface for managing configuration of network

                                type OutputConfig

                                type OutputConfig interface {
                                	// SetOutput specifies the destinations of standard output and standard error of
                                	// particular kinds of an output stream.
                                	// Valid values include:
                                	//	- init:		the output of cloudinit itself
                                	//	- config:	cloud-config caused output
                                	//	- final:	the final output of cloudinit (plus that set with SetFinalMessage)
                                	//	- all:		all of the above
                                	// Both stdout and stderr can take the following forms:
                                	//	- > file:	write to given file. Will truncate of file exists
                                	//	- >>file:	append to given file
                                	//	- | command:	pipe output to given command
                                	SetOutput(OutputKind, string, string)
                                
                                	// Output returns the destination set by SetOutput for the given OutputKind.
                                	// If it has not been previously set, empty strings are returned.
                                	Output(OutputKind) (string, string)
                                }

                                  OutputConfig is the interface for all stdout and stderr setting options.

                                  type OutputKind

                                  type OutputKind string

                                    OutputKind represents the available destinations for command output as sent through the cloudnit cloudconfig

                                    const (
                                    	// the output of cloudinit iself
                                    	OutInit OutputKind = "init"
                                    	// cloud-config caused output
                                    	OutConfig OutputKind = "config"
                                    	// the final output of cloudinit
                                    	OutFinal OutputKind = "final"
                                    	// all of the above
                                    	OutAll OutputKind = "all"
                                    )

                                      The constant output redirection options available to be passed to cloudinit

                                      type PackageManagerProxyConfig

                                      type PackageManagerProxyConfig interface {
                                      	AptProxy() proxy.Settings
                                      	AptMirror() string
                                      	SnapProxy() proxy.Settings
                                      	SnapStoreAssertions() string
                                      	SnapStoreProxyID() string
                                      	SnapStoreProxyURL() string
                                      }

                                        PackageManagerProxyConfig provides access to the proxy settings for various package managers.

                                        type PackageMirrorConfig

                                        type PackageMirrorConfig interface {
                                        	// SetPackageMirror sets the URL to be used as the mirror for
                                        	// pulling packages by the system's specific package manager.
                                        	SetPackageMirror(string)
                                        
                                        	// UnsetPackageMirror unsets the value set by SetPackageMirror
                                        	// If it has not been previously set, no error occurs.
                                        	UnsetPackageMirror()
                                        
                                        	// PackageMirror returns the URL of the package mirror set by
                                        	// SetPackageMirror or an empty string if not previously set.
                                        	PackageMirror() string
                                        }

                                          PackageMirrorConfig is the interface for package mirror settings on a cloudconfig.

                                          type PackageProxyConfig

                                          type PackageProxyConfig interface {
                                          	// SetPackageProxy sets the URL to be used as a proxy by the
                                          	// specific package manager
                                          	SetPackageProxy(string)
                                          
                                          	// UnsetPackageProxy unsets the option set by SetPackageProxy
                                          	// If it has not been previously set, no error occurs
                                          	UnsetPackageProxy()
                                          
                                          	// PackageProxy returns the URL of the proxy server set using
                                          	// SetPackageProxy or an empty string if it has not been set
                                          	PackageProxy() string
                                          }

                                            PackageProxyConfig is the interface for packaging proxy settings on a cloudconfig

                                            type PackageSourcesConfig

                                            type PackageSourcesConfig interface {
                                            	// AddPackageSource adds a new repository and optional key to be
                                            	// used as a package source by the system's specific package manager.
                                            	AddPackageSource(packaging.PackageSource)
                                            
                                            	// PackageSources returns all sources set with AddPackageSource.
                                            	PackageSources() []packaging.PackageSource
                                            
                                            	// AddPackagePreferences adds the necessary options and/or bootcmds to
                                            	// enable the given packaging.PackagePreferences.
                                            	AddPackagePreferences(packaging.PackagePreferences)
                                            
                                            	// PackagePreferences returns the previously-added PackagePreferences.
                                            	PackagePreferences() []packaging.PackagePreferences
                                            }

                                              PackageSourceConfig is the interface for package source settings on a cloudconfig.

                                              type PackagingConfig

                                              type PackagingConfig interface {
                                              	// AddPackage adds a package to be installed on *first* boot.
                                              	AddPackage(string)
                                              
                                              	// RemovePackage removes a package from the list of to be installed packages
                                              	// If the package has not been previously installed, no error occurs.
                                              	RemovePackage(string)
                                              
                                              	// Packages returns a list of all packages that will be installed.
                                              	Packages() []string
                                              }

                                                PackagingConfig is the interface for all packaging-related operations.

                                                type PreparedConfig

                                                type PreparedConfig struct {
                                                	InterfaceNames   []string
                                                	AutoStarted      []string
                                                	DNSServers       []string
                                                	DNSSearchDomains []string
                                                	NameToAddress    map[string]string
                                                	NameToRoutes     map[string][]corenetwork.Route
                                                	NameToMTU        map[string]int
                                                	Gateway4Address  string
                                                	Gateway6Address  string
                                                }

                                                  PreparedConfig holds all the necessary information to render a persistent network config to a file.

                                                  func PrepareNetworkConfigFromInterfaces

                                                  func PrepareNetworkConfigFromInterfaces(interfaces corenetwork.InterfaceInfos) (*PreparedConfig, error)

                                                    PrepareNetworkConfigFromInterfaces collects the necessary information to render a persistent network config from the given slice of network.InterfaceInfo. The result always includes the loopback interface.

                                                    type RenderConfig

                                                    type RenderConfig interface {
                                                    	// Renders the current cloud config as valid YAML
                                                    	RenderYAML() ([]byte, error)
                                                    
                                                    	// Renders a script that will execute the cloud config
                                                    	// It is used over ssh for bootstrapping with the manual provider.
                                                    	RenderScript() (string, error)
                                                    
                                                    	// ShellRenderer returns the shell renderer of this particular instance.
                                                    	ShellRenderer() shell.Renderer
                                                    	// contains filtered or unexported methods
                                                    }

                                                      RenderConfig provides various ways to render a CloudConfig.

                                                      type RootUserConfig

                                                      type RootUserConfig interface {
                                                      	// SetDisableRoot sets whether ssh login to the root account of the new server
                                                      	// through the ssh authorized key provided with the config should be disabled.
                                                      	// This option is set to true (ie. disabled) by default.
                                                      	SetDisableRoot(bool)
                                                      
                                                      	// UnsetDisable unsets the value set with SetDisableRoot, returning it to the
                                                      	// cloudinit-defined default of true.
                                                      	UnsetDisableRoot()
                                                      
                                                      	// DisableRoot returns the value set by SetDisableRoot or false if the
                                                      	// option had not been previously set.
                                                      	DisableRoot() bool
                                                      }

                                                        RootUserConfig is the interface for all root user-related settings.

                                                        type RunCmdsConfig

                                                        type RunCmdsConfig interface {
                                                        	// AddRunCmd adds a command to be executed on *first* boot.
                                                        	// It can receive any number of string arguments, which will be joined into
                                                        	// a single command and passed to cloudinit to be executed.
                                                        	// NOTE: metacharacters will *not* be escaped!
                                                        	AddRunCmd(...string)
                                                        
                                                        	// AddScripts simply calls AddRunCmd on every string passed to it.
                                                        	// NOTE: this means that each given string must be a full command plus
                                                        	// all of its arguments.
                                                        	// NOTE: metacharacters will not be escaped.
                                                        	AddScripts(...string)
                                                        
                                                        	// PrependRunCmd adds a command to the beginning of the list of commands
                                                        	// to be run on first boot.
                                                        	PrependRunCmd(...string)
                                                        
                                                        	// RemoveRunCmd removes the given command from the list of commands to be
                                                        	// run on first boot. If it has not been previously added, no error occurs.
                                                        	RemoveRunCmd(string)
                                                        
                                                        	// RunCmds returns all the commands added with AddRunCmd or AddScript.
                                                        	RunCmds() []string
                                                        }

                                                          RunCmdsConfig is the interface for all operations on first-boot commands.

                                                          type SSHAuthorizedKeysConfig

                                                          type SSHAuthorizedKeysConfig interface {
                                                          	// SetSSHAuthorizedKeys puts a set of authorized keys for the default
                                                          	// user in the ~/.ssh/authorized_keys file.
                                                          	SetSSHAuthorizedKeys(string)
                                                          }

                                                            SSHAuthorizedKeysConfig is the interface for adding ssh authorized keys.

                                                            type SSHKey

                                                            type SSHKey struct {
                                                            	// Private is the SSH private key.
                                                            	Private string
                                                            
                                                            	// Public is the SSH public key.
                                                            	Public string
                                                            }

                                                              SSHKey is an SSH key pair.

                                                              type SSHKeyType

                                                              type SSHKeyType string

                                                                SSHKeyType is the type of the four used key types passed to cloudinit through the cloudconfig

                                                                const (
                                                                	RSAPrivate SSHKeyType = "rsa_private"
                                                                	RSAPublic  SSHKeyType = "rsa_public"
                                                                	DSAPrivate SSHKeyType = "dsa_private"
                                                                	DSAPublic  SSHKeyType = "dsa_public"
                                                                )

                                                                  The constant SSH key types sent to cloudinit through the cloudconfig

                                                                  type SSHKeys

                                                                  type SSHKeys struct {
                                                                  	RSA *SSHKey
                                                                  }

                                                                    SSHKeys contains SSH host keys to configure on a machine.

                                                                    type SSHKeysConfig

                                                                    type SSHKeysConfig interface {
                                                                    	// SetSSHKeys sets the SSH host keys for the machine.
                                                                    	SetSSHKeys(SSHKeys)
                                                                    }

                                                                      SSHKeysConfig is the interface for setting ssh host keys.

                                                                      type SystemUpdateConfig

                                                                      type SystemUpdateConfig interface {
                                                                      	// SetSystemUpdate sets whether the system should refresh the local package
                                                                      	// database on first boot.
                                                                      	// NOTE: This option is active in cloudinit by default and must be
                                                                      	// explicitly set to false if it is not desired.
                                                                      	SetSystemUpdate(bool)
                                                                      
                                                                      	// UnsetSystemUpdate unsets the package list updating option set by
                                                                      	// SetSystemUpdate, returning it to the cloudinit *default of true*.
                                                                      	// If the option has not previously been set, no error occurs.
                                                                      	UnsetSystemUpdate()
                                                                      
                                                                      	// SystemUpdate returns the value set with SetSystemUpdate or false
                                                                      	// NOTE: even though not set, the cloudinit-defined default is true.
                                                                      	SystemUpdate() bool
                                                                      }

                                                                        SystemUpdateConfig is the interface for managing all system update options.

                                                                        type SystemUpgradeConfig

                                                                        type SystemUpgradeConfig interface {
                                                                        	// SetSystemUpgrade sets whether cloud-init should run the process of upgrading
                                                                        	// all the packages with available newer versions on the machine's *first* boot.
                                                                        	SetSystemUpgrade(bool)
                                                                        
                                                                        	// UnsetSystemUpgrade unsets the value set by SetSystemUpgrade.
                                                                        	// If the option has not previously been set, no error occurs.
                                                                        	UnsetSystemUpgrade()
                                                                        
                                                                        	// SystemUpgrade returns the value set by SetSystemUpgrade or
                                                                        	// false if no call to SetSystemUpgrade has been made.
                                                                        	SystemUpgrade() bool
                                                                        }

                                                                          SystemUpgradeConfig is the interface for managing all system upgrade settings.

                                                                          type User

                                                                          type User struct {
                                                                          	// Login name for the user.
                                                                          	Name string
                                                                          
                                                                          	// Additional groups to add the user to.
                                                                          	Groups []string
                                                                          
                                                                          	// Path to shell to use by default.
                                                                          	Shell string
                                                                          
                                                                          	// SSH keys to add to the authorized keys file.
                                                                          	SSHAuthorizedKeys string
                                                                          
                                                                          	// Sudo directives to add.
                                                                          	Sudo []string
                                                                          }

                                                                          type UsersConfig

                                                                          type UsersConfig interface {
                                                                          	// AddUser sets a new user to be created with the given configuration.
                                                                          	AddUser(*User)
                                                                          
                                                                          	// UnsetUsers unsets any users set in the config, meaning the default
                                                                          	// user specified in the image cloud config will be used.
                                                                          	UnsetUsers()
                                                                          }

                                                                            UsersConfig is the interface for managing user additions

                                                                            type WrittenFilesConfig

                                                                            type WrittenFilesConfig interface {
                                                                            	// AddRunTextFile simply issues some AddRunCmd's to set the contents of a
                                                                            	// given file with the specified file permissions on *first* boot.
                                                                            	// NOTE: if the file already exists, it will be truncated.
                                                                            	AddRunTextFile(string, string, uint)
                                                                            
                                                                            	// AddBootTextFile simply issues some AddBootCmd's to set the contents of a
                                                                            	// given file with the specified file permissions on *every* boot.
                                                                            	// NOTE: if the file already exists, it will be truncated.
                                                                            	AddBootTextFile(string, string, uint)
                                                                            
                                                                            	// AddRunBinaryFile simply issues some AddRunCmd's to set the binary contents
                                                                            	// of a given file with the specified file permissions on *first* boot.
                                                                            	// NOTE: if the file already exists, it will be truncated.
                                                                            	AddRunBinaryFile(string, []byte, uint)
                                                                            }

                                                                              WrittenFilesConfig is the interface for all file writing operations.

                                                                              Directories

                                                                              Path Synopsis