Documentation
¶
Overview ¶
The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format. See http://launchpad.net/simplestreams and in particular the doc/README file in that project for more information about the file formats.
The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format. See http://launchpad.net/simplestreams and in particular the doc/README file in that project for more information about the file formats.
Index ¶
- Constants
- Variables
- func Archive(w io.Writer, dir string) (string, error)
- func FindBootstrapTools(cloudInst environs.ConfigGetter, params BootstrapToolsParams) (list coretools.List, err error)
- func FindExactTools(cloudInst environs.ConfigGetter, vers version.Number, series string, ...) (t *coretools.Tools, err error)
- func FindInstanceTools(cloudInst environs.ConfigGetter, vers version.Number, series string, ...) (list coretools.List, err error)
- func FindTools(cloudInst environs.ConfigGetter, majorVersion, minorVersion int, ...) (list coretools.List, err error)
- func FindToolsForCloud(sources []simplestreams.DataSource, cloudSpec simplestreams.CloudSpec, ...) (list coretools.List, err error)
- func GetMetadataSources(env environs.ConfigGetter) ([]simplestreams.DataSource, error)
- func GetMetadataSourcesWithRetries(env environs.ConfigGetter, allowRetry bool) ([]simplestreams.DataSource, error)
- func MarshalToolsMetadataIndexJSON(metadata []*ToolsMetadata, updated time.Time) (out []byte, err error)
- func MarshalToolsMetadataJSON(metadata []*ToolsMetadata, updated time.Time) (index, products []byte, err error)
- func MarshalToolsMetadataProductsJSON(metadata []*ToolsMetadata, updated time.Time) (out []byte, err error)
- func MergeAndWriteMetadata(stor storage.Storage, tools coretools.List, writeMirrors ShouldWriteMirrors) error
- func ReadList(stor storage.StorageReader, majorVersion, minorVersion int) (coretools.List, error)
- func ResolveMetadata(stor storage.StorageReader, metadata []*ToolsMetadata) error
- func Sort(metadata []*ToolsMetadata)
- func StorageName(vers version.Binary) string
- func TestingPatchBootstrapFindTools(stub findtoolsfunc) func()
- func ToolsURL(source string) (string, error)
- func ValidateToolsMetadata(params *ToolsMetadataLookupParams) ([]string, *simplestreams.ResolveInfo, error)
- func WriteMetadata(stor storage.Storage, metadata []*ToolsMetadata, ...) error
- type BootstrapToolsParams
- type BundleToolsFunc
- type MetadataFile
- type ShouldWriteMirrors
- type SupportsCustomSources
- type ToolsConstraint
- type ToolsMetadata
- func Fetch(sources []simplestreams.DataSource, indexPath string, cons *ToolsConstraint, ...) ([]*ToolsMetadata, *simplestreams.ResolveInfo, error)
- func MergeMetadata(tmlist1, tmlist2 []*ToolsMetadata) ([]*ToolsMetadata, error)
- func MetadataFromTools(toolsList coretools.List) []*ToolsMetadata
- func ReadMetadata(store storage.StorageReader) ([]*ToolsMetadata, error)
- type ToolsMetadataLookupParams
Constants ¶
const ( ProductMetadataPath = "streams/v1/com.ubuntu.juju:released:tools.json" ToolsContentId = "com.ubuntu.juju:released:tools" )
const ( WriteMirrors = ShouldWriteMirrors(true) DoNotWriteMirrors = ShouldWriteMirrors(false) )
const (
ContentDownload = "content-download"
)
const DoNotAllowRetry = false
Define some boolean parameter values.
Variables ¶
var DefaultBaseURL = "https://streams.canonical.com/juju/tools"
This needs to be a var so we can override it for testing.
var ErrNoTools = errors.New("no tools available")
var PublicMirrorsInfo = `` /* 222-byte string literal not displayed */
Functions ¶
func Archive ¶
Archive writes the executable files found in the given directory in gzipped tar format to w, returning the SHA256 hash of the resulting file. An error is returned if an entry inside dir is not a regular executable file.
func FindBootstrapTools ¶
func FindBootstrapTools(cloudInst environs.ConfigGetter, params BootstrapToolsParams) (list coretools.List, err error)
FindBootstrapTools returns a ToolsList containing only those tools with which it would be reasonable to launch an environment's first machine, given the supplied constraints. If a specific agent version is not requested, all tools matching the current major.minor version are chosen.
func FindExactTools ¶
func FindExactTools(cloudInst environs.ConfigGetter, vers version.Number, series string, arch string) (t *coretools.Tools, err error)
FindExactTools returns only the tools that match the supplied version.
func FindInstanceTools ¶
func FindInstanceTools(cloudInst environs.ConfigGetter, vers version.Number, series string, arch *string) (list coretools.List, err error)
FindInstanceTools returns a ToolsList containing only those tools with which it would be reasonable to start a new instance, given the supplied series and arch.
func FindTools ¶
func FindTools(cloudInst environs.ConfigGetter, majorVersion, minorVersion int, filter coretools.Filter, allowRetry bool) (list coretools.List, err error)
FindTools returns a List containing all tools with a given major.minor version number available in the cloud instance, filtered by filter. If minorVersion = -1, then only majorVersion is considered. If no *available* tools have the supplied major.minor version number, or match the supplied filter, the function returns a *NotFoundError.
func FindToolsForCloud ¶
func FindToolsForCloud(sources []simplestreams.DataSource, cloudSpec simplestreams.CloudSpec, majorVersion, minorVersion int, filter coretools.Filter) (list coretools.List, err error)
FindToolsForCloud returns a List containing all tools with a given major.minor version number and cloudSpec, filtered by filter. If minorVersion = -1, then only majorVersion is considered. If no *available* tools have the supplied major.minor version number, or match the supplied filter, the function returns a *NotFoundError.
func GetMetadataSources ¶
func GetMetadataSources(env environs.ConfigGetter) ([]simplestreams.DataSource, error)
GetMetadataSources returns the sources to use when looking for simplestreams tools metadata. If env implements SupportsCustomSurces, the sources returned from that method will also be considered. The sources are configured to not use retries.
func GetMetadataSourcesWithRetries ¶
func GetMetadataSourcesWithRetries(env environs.ConfigGetter, allowRetry bool) ([]simplestreams.DataSource, error)
GetMetadataSourcesWithRetries returns the sources to use when looking for simplestreams tools metadata. If env implements SupportsCustomSurces, the sources returned from that method will also be considered. The sources are configured to use retries according to the value of allowRetry.
func MarshalToolsMetadataIndexJSON ¶
func MarshalToolsMetadataIndexJSON(metadata []*ToolsMetadata, updated time.Time) (out []byte, err error)
MarshalToolsMetadataIndexJSON marshals tools metadata to index JSON.
updated is the time at which the JSON file was updated.
func MarshalToolsMetadataJSON ¶
func MarshalToolsMetadataJSON(metadata []*ToolsMetadata, updated time.Time) (index, products []byte, err error)
MarshalToolsMetadataJSON marshals tools metadata to index and products JSON.
updated is the time at which the JSON file was updated.
func MarshalToolsMetadataProductsJSON ¶
func MarshalToolsMetadataProductsJSON(metadata []*ToolsMetadata, updated time.Time) (out []byte, err error)
MarshalToolsMetadataProductsJSON marshals tools metadata to products JSON.
updated is the time at which the JSON file was updated.
func MergeAndWriteMetadata ¶
func MergeAndWriteMetadata(stor storage.Storage, tools coretools.List, writeMirrors ShouldWriteMirrors) error
MergeAndWriteMetadata reads the existing metadata from storage (if any), and merges it with metadata generated from the given tools list. The resulting metadata is written to storage.
func ReadList ¶
ReadList returns a List of the tools in store with the given major.minor version. If minorVersion = -1, then only majorVersion is considered. If store contains no such tools, it returns ErrNoMatches.
func ResolveMetadata ¶
func ResolveMetadata(stor storage.StorageReader, metadata []*ToolsMetadata) error
ResolveMetadata resolves incomplete metadata by fetching the tools from storage and computing the size and hash locally.
func Sort ¶
func Sort(metadata []*ToolsMetadata)
Sort sorts a slice of ToolsMetadata in ascending order of their version in order to ensure the results of Fetch are ordered deterministically.
func StorageName ¶
StorageName returns the name that is used to store and retrieve the given version of the juju tools.
func TestingPatchBootstrapFindTools ¶
func TestingPatchBootstrapFindTools(stub findtoolsfunc) func()
func ToolsURL ¶
ToolsURL returns a valid tools URL constructed from source. source may be a directory, or a URL like file://foo or http://foo.
func ValidateToolsMetadata ¶
func ValidateToolsMetadata(params *ToolsMetadataLookupParams) ([]string, *simplestreams.ResolveInfo, error)
ValidateToolsMetadata attempts to load tools metadata for the specified cloud attributes and returns any tools versions found, or an error if the metadata could not be loaded.
func WriteMetadata ¶
func WriteMetadata(stor storage.Storage, metadata []*ToolsMetadata, writeMirrors ShouldWriteMirrors) error
WriteMetadata writes the given tools metadata to the given storage.
Types ¶
type BootstrapToolsParams ¶
type BootstrapToolsParams struct { Version *version.Number Arch *string Series string AllowRetry bool }
BootstrapToolsParams contains parameters for FindBootstrapTools
type BundleToolsFunc ¶
type BundleToolsFunc func(w io.Writer, forceVersion *version.Number) (version.Binary, string, error)
BundleToolsFunc is a function which can bundle all the current juju tools in gzipped tar format to the given writer.
var BundleTools BundleToolsFunc = bundleTools
Override for testing.
type MetadataFile ¶
type ShouldWriteMirrors ¶
type ShouldWriteMirrors bool
type SupportsCustomSources ¶
type SupportsCustomSources interface {
GetToolsSources() ([]simplestreams.DataSource, error)
}
SupportsCustomSources represents an environment that can host tools metadata at provider specific sources.
type ToolsConstraint ¶
type ToolsConstraint struct { simplestreams.LookupParams Version version.Number MajorVersion int MinorVersion int Released bool }
ToolsConstraint defines criteria used to find a tools metadata record.
func NewGeneralToolsConstraint ¶
func NewGeneralToolsConstraint(majorVersion, minorVersion int, released bool, params simplestreams.LookupParams) *ToolsConstraint
NewGeneralToolsConstraint returns a ToolsConstraint for tools with matching major/minor version numbers.
func NewVersionedToolsConstraint ¶
func NewVersionedToolsConstraint(vers version.Number, params simplestreams.LookupParams) *ToolsConstraint
NewVersionedToolsConstraint returns a ToolsConstraint for a tools with a specific version.
func (*ToolsConstraint) Ids ¶
func (tc *ToolsConstraint) Ids() ([]string, error)
Ids generates a string array representing product ids formed similarly to an ISCSI qualified name (IQN).
type ToolsMetadata ¶
type ToolsMetadata struct { Release string `json:"release"` Version string `json:"version"` Arch string `json:"arch"` Size int64 `json:"size"` Path string `json:"path"` FullPath string `json:"-"` FileType string `json:"ftype"` SHA256 string `json:"sha256"` }
ToolsMetadata holds information about a particular tools tarball.
func Fetch ¶
func Fetch( sources []simplestreams.DataSource, indexPath string, cons *ToolsConstraint, onlySigned bool) ([]*ToolsMetadata, *simplestreams.ResolveInfo, error)
Fetch returns a list of tools for the specified cloud matching the constraint. The base URL locations are as specified - the first location which has a file is the one used. Signed data is preferred, but if there is no signed data available and onlySigned is false, then unsigned data is used.
func MergeMetadata ¶
func MergeMetadata(tmlist1, tmlist2 []*ToolsMetadata) ([]*ToolsMetadata, error)
MergeMetadata merges the given tools metadata. If metadata for the same tools version exists in both lists, an entry with non-empty size/SHA256 takes precedence; if the two entries have different sizes/hashes, then an error is returned.
func MetadataFromTools ¶
func MetadataFromTools(toolsList coretools.List) []*ToolsMetadata
MetadataFromTools returns a tools metadata list derived from the given tools list. The size and sha256 will not be computed if missing.
func ReadMetadata ¶
func ReadMetadata(store storage.StorageReader) ([]*ToolsMetadata, error)
ReadMetadata returns the tools metadata from the given storage.
func (*ToolsMetadata) String ¶
func (t *ToolsMetadata) String() string
type ToolsMetadataLookupParams ¶
type ToolsMetadataLookupParams struct { simplestreams.MetadataLookupParams Version string Major int Minor int }
ToolsMetadataLookupParams is used to query metadata for matching tools.