diff --git a/Makefile b/Makefile index c5e1c4933..a53005026 100644 --- a/Makefile +++ b/Makefile @@ -11,6 +11,7 @@ PROJECT = github.com/weaveworks/ignite APIS_DIR = ${PROJECT}/pkg/apis API_DIRS = ${APIS_DIR}/ignite/v1alpha1,${APIS_DIR}/meta/v1alpha1 CACHE_DIR = $(shell pwd)/bin/cache +API_DOCS = docs/api-reference/ignite.md docs/api-reference/meta.md all: binary binary: @@ -39,7 +40,7 @@ ifeq ($(IS_DIRTY),0) docker push ${DOCKER_USER}/ignite:${GIT_VERSION} endif -tidy: +tidy: $(API_DOCS) go mod tidy go mod vendor gofmt -s -w pkg cmd @@ -47,6 +48,18 @@ tidy: hack/generate-client.sh go run hack/cobra.go +.PHONY: $(API_DOCS) +$(API_DOCS): docs/api-reference/%.md: $(CACHE_DIR)/go/bin/godoc2md + mkdir -p $$(dirname $@) bin/tmp/$* + mv $(shell pwd)/pkg/apis/$*/v1alpha1/zz_generated* bin/tmp/$* + $(MAKE) shell COMMAND="/go/bin/godoc2md /go/src/${PROJECT}/pkg/apis/$*/v1alpha1 > $@" + mv bin/tmp/$*/*.go $(shell pwd)/pkg/apis/$*/v1alpha1/ + rm -r bin/tmp/$* + +$(CACHE_DIR)/go/bin/godoc2md: + curl -sSL https://github.com/luxas/godoc2md/releases/download/v0.1.0/godoc2md > $@ + chmod +x $@ + shell: mkdir -p $(CACHE_DIR)/go $(CACHE_DIR)/cache docker run -it \ diff --git a/docs/api-reference/ignite.md b/docs/api-reference/ignite.md new file mode 100644 index 000000000..c8395c4a1 --- /dev/null +++ b/docs/api-reference/ignite.md @@ -0,0 +1,570 @@ + + +# v1alpha1 +`import "/go/src/github.com/weaveworks/ignite/pkg/apis/ignite/v1alpha1"` + +* [Overview](#pkg-overview) +* [Index](#pkg-index) + +## Overview ++k8s:deepcopy-gen=package ++k8s:defaulter-gen=TypeMeta + + + + +## Index +* [Constants](#pkg-constants) +* [Variables](#pkg-variables) +* [func SetDefaults_ImageSource(obj *ImageSource)](#SetDefaults_ImageSource) +* [func SetDefaults_PoolSpec(obj *PoolSpec)](#SetDefaults_PoolSpec) +* [func SetDefaults_VMSpec(obj *VMSpec)](#SetDefaults_VMSpec) +* [func SetDefaults_VMStatus(obj *VMStatus)](#SetDefaults_VMStatus) +* [type FileMapping](#FileMapping) +* [type Image](#Image) +* [type ImageClaim](#ImageClaim) +* [type ImageSource](#ImageSource) +* [type ImageSourceType](#ImageSourceType) +* [type ImageSpec](#ImageSpec) +* [type Kernel](#Kernel) +* [type KernelClaim](#KernelClaim) +* [type KernelSpec](#KernelSpec) +* [type Pool](#Pool) +* [type PoolDevice](#PoolDevice) +* [type PoolDeviceType](#PoolDeviceType) +* [type PoolSpec](#PoolSpec) +* [type PoolStatus](#PoolStatus) +* [type PortMapping](#PortMapping) +* [type SSH](#SSH) +* [type VM](#VM) +* [type VMSpec](#VMSpec) +* [type VMState](#VMState) +* [type VMStatus](#VMStatus) + + +#### Package files +[defaults.go](/src/target/defaults.go) [doc.go](/src/target/doc.go) [register.go](/src/target/register.go) [types.go](/src/target/types.go) + + +## Constants +``` go +const ( + // GroupName is the group name use in this package + GroupName = "ignite.weave.works" + + // VMKind returns the kind for the VM API type + VMKind = "VM" + // KernelKind returns the kind for the Kernel API type + KernelKind = "Kernel" + // PoolKind returns the kind for the Pool API type + PoolKind = "Pool" + // ImageKind returns the kind for the Image API type + ImageKind = "Image" +) +``` + +## Variables +``` go +var ( + // SchemeBuilder the schema builder + SchemeBuilder = runtime.NewSchemeBuilder( + addKnownTypes, + addDefaultingFuncs, + ) + + AddToScheme = localSchemeBuilder.AddToScheme +) +``` +``` go +var SchemeGroupVersion = schema.GroupVersion{ + Group: GroupName, + Version: "v1alpha1", +} +``` +SchemeGroupVersion is group version used to register these objects + + + +## func [SetDefaults_ImageSource](/src/target/defaults.go?s=263:309#L13) +``` go +func SetDefaults_ImageSource(obj *ImageSource) +``` + + +## func [SetDefaults_PoolSpec](/src/target/defaults.go?s=349:389#L17) +``` go +func SetDefaults_PoolSpec(obj *PoolSpec) +``` + + +## func [SetDefaults_VMSpec](/src/target/defaults.go?s=915:951#L39) +``` go +func SetDefaults_VMSpec(obj *VMSpec) +``` + + +## func [SetDefaults_VMStatus](/src/target/defaults.go?s=1338:1378#L59) +``` go +func SetDefaults_VMStatus(obj *VMStatus) +``` + + + +## type [FileMapping](/src/target/types.go?s=6878:6973#L188) +``` go +type FileMapping struct { + HostPath string `json:"hostPath"` + VMPath string `json:"vmPath"` +} + +``` +FileMapping defines mappings between files on the host and VM + + + + + + + + + + +## type [Image](/src/target/types.go?s=285:749#L13) +``` go +type Image struct { + metav1.TypeMeta `json:",inline"` + // meta.ObjectMeta is also embedded into the struct, and defines the human-readable name, and the machine-readable ID + // Name is available at the .metadata.name JSON path + // ID is available at the .metadata.uid JSON path (the Go type is k8s.io/apimachinery/pkg/types.UID, which is only a typed string) + meta.ObjectMeta `json:"metadata"` + + Spec ImageSpec `json:"spec"` +} + +``` +Image represents a cached OCI image ready to be used with Ignite ++k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object + + + + + + + + + + +## type [ImageClaim](/src/target/types.go?s=6329:6502#L168) +``` go +type ImageClaim struct { + Type ImageSourceType `json:"type"` + Ref string `json:"ref"` + // TODO: Temporary ID for the old metadata handling + ID string `json:"ID"` +} + +``` +ImageClaim specifies a claim to import an image + + + + + + + + + + +## type [ImageSource](/src/target/types.go?s=1152:1509#L38) +``` go +type ImageSource struct { + // Type defines how the image was imported + Type ImageSourceType `json:"type"` + // ID defines the source's ID (e.g. the Docker image ID) + ID string `json:"id"` + // Name defines the user-friendly name of the imported source + Name string `json:"name"` + // Size defines the size of the source in bytes + Size meta.Size `json:"size"` +} + +``` +ImageSource defines where the image was imported from + + + + + + + + + + +## type [ImageSourceType](/src/target/types.go?s=932:959#L30) +``` go +type ImageSourceType string +``` +ImageSourceType is an enum of different supported Image Source Types + + +``` go +const ( + // ImageSourceTypeDocker defines that the image is imported from Docker + ImageSourceTypeDocker ImageSourceType = "Docker" +) +``` + + + + + + + + + +## type [ImageSpec](/src/target/types.go?s=797:858#L25) +``` go +type ImageSpec struct { + Source ImageSource `json:"source"` +} + +``` +ImageSpec declares what the image contains + + + + + + + + + + +## type [Kernel](/src/target/types.go?s=4071:4538#L114) +``` go +type Kernel struct { + metav1.TypeMeta `json:",inline"` + // meta.ObjectMeta is also embedded into the struct, and defines the human-readable name, and the machine-readable ID + // Name is available at the .metadata.name JSON path + // ID is available at the .metadata.uid JSON path (the Go type is k8s.io/apimachinery/pkg/types.UID, which is only a typed string) + meta.ObjectMeta `json:"metadata"` + + Spec KernelSpec `json:"spec"` +} + +``` +Kernel is a serializable object that caches information about imported kernels +This file is stored in /var/lib/firecracker/kernels/{oci-image-digest}/metadata.json ++k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object + + + + + + + + + + +## type [KernelClaim](/src/target/types.go?s=6560:6648#L176) +``` go +type KernelClaim struct { + ID string `json:"ID"` + CmdLine string `json:"cmdline"` +} + +``` +TODO: Temporary helper for the old metadata handling + + + + + + + + + + +## type [KernelSpec](/src/target/types.go?s=4591:4797#L126) +``` go +type KernelSpec struct { + Version string `json:"version"` + Source ImageSource `json:"source"` +} + +``` +KernelSpec describes the properties of a kernel + + + + + + + + + + +## type [Pool](/src/target/types.go?s=1965:2147#L59) +``` go +type Pool struct { + metav1.TypeMeta `json:",inline"` + + Spec PoolSpec `json:"spec"` + Status PoolStatus `json:"status"` +} + +``` +Pool defines device mapper pool database +This file is managed by the snapshotter part of Ignite, and the file (existing as a singleton) +is present at /var/lib/firecracker/snapshotter/pool.json ++k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object + + + + + + + + + + +## type [PoolDevice](/src/target/types.go?s=3438:3828#L101) +``` go +type PoolDevice struct { + Size meta.Size `json:"size"` + Parent meta.DMID `json:"parent"` + // Type specifies the type of the contents of the device + Type PoolDeviceType `json:"type"` + // MetadataPath points to the JSON/YAML file with metadata about this device + // This is most often of the format /var/lib/firecracker/{type}/{id}/metadata.json + MetadataPath string `json:"metadataPath"` +} + +``` +PoolDevice defines one device in the pool + + + + + + + + + + +## type [PoolDeviceType](/src/target/types.go?s=3167:3193#L91) +``` go +type PoolDeviceType string +``` + +``` go +const ( + PoolDeviceTypeImage PoolDeviceType = "Image" + PoolDeviceTypeResize PoolDeviceType = "Resize" + PoolDeviceTypeKernel PoolDeviceType = "Kernel" + PoolDeviceTypeVM PoolDeviceType = "VM" +) +``` + + + + + + + + + +## type [PoolSpec](/src/target/types.go?s=2194:2907#L69) +``` go +type PoolSpec struct { + // MetadataSize specifies the size of the pool's metadata + MetadataSize meta.Size `json:"metadataSize"` + // DataSize specifies the size of the pool's data + DataSize meta.Size `json:"dataSize"` + // AllocationSize specifies the smallest size that can be allocated at a time + AllocationSize meta.Size `json:"allocationSize"` + // MetadataPath points to the file where device mapper stores all metadata information + // Defaults to constants.SNAPSHOTTER_METADATA_PATH + MetadataPath string `json:"metadataPath"` + // DataPath points to the backing physical device or sparse file (to be loop mounted) for the pool + // Defaults to constants.SNAPSHOTTER_DATA_PATH + DataPath string `json:"dataPath"` +} + +``` +PoolSpec defines the Pool's specification + + + + + + + + + + +## type [PoolStatus](/src/target/types.go?s=2957:3165#L85) +``` go +type PoolStatus struct { + // The Devices array needs to contain pointers to accommodate "holes" in the mapping + // Where devices have been deleted, the pointer is nil + Devices []*PoolDevice `json:"devices"` +} + +``` +PoolStatus defines the Pool's current status + + + + + + + + + + +## type [PortMapping](/src/target/types.go?s=6716:6811#L182) +``` go +type PortMapping struct { + HostPort uint64 `json:"hostPort"` + VMPort uint64 `json:"vmPort"` +} + +``` +PortMapping defines a port mapping between the VM and the host + + + + + + + + + + +## type [SSH](/src/target/types.go?s=7036:7092#L194) +``` go +type SSH struct { + PublicKey string `json:"publicKey"` +} + +``` +SSH specifies different ways to connect via SSH to the VM + + + + + + + + + + +## type [VM](/src/target/types.go?s=4999:5456#L136) +``` go +type VM struct { + metav1.TypeMeta `json:",inline"` + // meta.ObjectMeta is also embedded into the struct, and defines the human-readable name, and the machine-readable ID + // Name is available at the .metadata.name JSON path + // ID is available at the .metadata.uid JSON path (the Go type is k8s.io/apimachinery/pkg/types.UID, which is only a typed string) + meta.ObjectMeta `json:"metadata"` + + Spec VMSpec `json:"spec"` + Status VMStatus `json:"status"` +} + +``` +VM represents a virtual machine run by Firecracker +These files are stored in /var/lib/firecracker/vm/{vm-id}/metadata.json ++k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object + + + + + + + + + + +## type [VMSpec](/src/target/types.go?s=5504:6276#L148) +``` go +type VMSpec struct { + Image *ImageClaim `json:"image"` + // TODO: Temporary ID for the old metadata handling + Kernel *KernelClaim `json:"kernel"` + CPUs uint64 `json:"cpus"` + Memory meta.Size `json:"memory"` + DiskSize meta.Size `json:"diskSize"` + Ports []PortMapping `json:"ports,omitempty"` + // This will be done at either "ignite start" or "ignite create" time + // TODO: We might to revisit this later + CopyFiles []FileMapping `json:"copyFiles,omitempty"` + // SSH specifies how the SSH setup should be done + // SSH appends to CopyFiles when active + // nil here means "don't do anything special" + // An empty struct means "generate a new SSH key and copy it in" + // Specifying a path means "use this public key" + SSH *SSH `json:"ssh,omitempty"` +} + +``` +VMSpec describes the configuration of a VM + + + + + + + + + + +## type [VMState](/src/target/types.go?s=7145:7164#L199) +``` go +type VMState string +``` +VMState defines different states a VM can be in + + +``` go +const ( + VMStateCreated VMState = "Created" + VMStateRunning VMState = "Running" + VMStateStopped VMState = "Stopped" +) +``` + + + + + + + + + +## type [VMStatus](/src/target/types.go?s=7324:7428#L208) +``` go +type VMStatus struct { + State VMState `json:"state"` + IPAddresses []net.IP `json:"ipAddresses"` +} + +``` +VMStatus defines the status of a VM + + + + + + + + + + + + + + +- - - +Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md) diff --git a/docs/api-reference/meta.md b/docs/api-reference/meta.md new file mode 100644 index 000000000..7c814b196 --- /dev/null +++ b/docs/api-reference/meta.md @@ -0,0 +1,374 @@ + + +# v1alpha1 +`import "/go/src/github.com/weaveworks/ignite/pkg/apis/meta/v1alpha1"` + +* [Overview](#pkg-overview) +* [Index](#pkg-index) + +## Overview ++k8s:deepcopy-gen=package + + + + +## Index +* [Variables](#pkg-variables) +* [type APIType](#APIType) +* [type APITypeList](#APITypeList) +* [type DMID](#DMID) + * [func NewDMID(i int) DMID](#NewDMID) + * [func NewPoolDMID() DMID](#NewPoolDMID) + * [func (d *DMID) Index() int](#DMID.Index) + * [func (d *DMID) Pool() bool](#DMID.Pool) + * [func (d DMID) String() string](#DMID.String) +* [type Object](#Object) +* [type ObjectMeta](#ObjectMeta) + * [func (o *ObjectMeta) GetCreated() *metav1.Time](#ObjectMeta.GetCreated) + * [func (o *ObjectMeta) GetName() string](#ObjectMeta.GetName) + * [func (o *ObjectMeta) GetUID() string](#ObjectMeta.GetUID) + * [func (o *ObjectMeta) SetCreated(t *metav1.Time)](#ObjectMeta.SetCreated) + * [func (o *ObjectMeta) SetName(name string)](#ObjectMeta.SetName) + * [func (o *ObjectMeta) SetUID(uid string)](#ObjectMeta.SetUID) +* [type Size](#Size) + * [func NewSizeFromBytes(bytes uint64) Size](#NewSizeFromBytes) + * [func NewSizeFromSectors(sectors uint64) Size](#NewSizeFromSectors) + * [func NewSizeFromString(str string) (Size, error)](#NewSizeFromString) + * [func (s Size) Add(other Size) Size](#Size.Add) + * [func (s *Size) Int64() int64](#Size.Int64) + * [func (s *Size) MarshalJSON() ([]byte, error)](#Size.MarshalJSON) + * [func (s Size) Max(other Size) Size](#Size.Max) + * [func (s Size) Min(other Size) Size](#Size.Min) + * [func (s *Size) Sectors() uint64](#Size.Sectors) + * [func (s *Size) String() string](#Size.String) + * [func (s *Size) UnmarshalJSON(b []byte) error](#Size.UnmarshalJSON) +* [type UID](#UID) + * [func (u UID) String() string](#UID.String) + + +#### Package files +[doc.go](/src/target/doc.go) [meta.go](/src/target/meta.go) + + + +## Variables +``` go +var EmptySize = NewSizeFromBytes(0) +``` + + + +## type [APIType](/src/target/meta.go?s=379:471#L20) +``` go +type APIType struct { + metav1.TypeMeta `json:",inline"` + ObjectMeta `json:"metadata"` +} + +``` +APIType is a struct implementing Object, used for +unmarshalling unknown objects into this intermediate type +where .Name, .UID, .Kind and .APIVersion become easily available + + + + + + + + + + +## type [APITypeList](/src/target/meta.go?s=531:558#L26) +``` go +type APITypeList []*APIType +``` +APITypeList is a list of many pointers APIType objects + + + + + + + + + + +## type [DMID](/src/target/meta.go?s=3489:3522#L172) +``` go +type DMID struct { + // contains filtered or unexported fields +} + +``` +DMID specifies the format for device mapper IDs + + + + + + + +### func [NewDMID](/src/target/meta.go?s=3553:3577#L178) +``` go +func NewDMID(i int) DMID +``` + +### func [NewPoolDMID](/src/target/meta.go?s=3761:3784#L189) +``` go +func NewPoolDMID() DMID +``` + + + + +### func (\*DMID) [Index](/src/target/meta.go?s=3920:3946#L200) +``` go +func (d *DMID) Index() int +``` + + + +### func (\*DMID) [Pool](/src/target/meta.go?s=3868:3894#L196) +``` go +func (d *DMID) Pool() bool +``` + + + +### func (DMID) [String](/src/target/meta.go?s=4036:4065#L208) +``` go +func (d DMID) String() string +``` + + + +## type [Object](/src/target/meta.go?s=1638:1823#L69) +``` go +type Object interface { + runtime.Object + + GetName() string + SetName(string) + + // TODO: Use UID + GetUID() string + SetUID(string) + + GetCreated() *metav1.Time + SetCreated(t *metav1.Time) +} +``` +Object extends k8s.io/apimachinery's runtime.Object with +extra GetName() and GetUID() methods from ObjectMeta + + + + + + + + + + +## type [ObjectMeta](/src/target/meta.go?s=720:876#L31) +``` go +type ObjectMeta struct { + Name string `json:"name"` + UID UID `json:"uid,omitempty"` + Created *metav1.Time `json:"created,omitempty"` +} + +``` +ObjectMeta have to be embedded into any serializable object. +It provides the .GetName() and .GetUID() methods that help +implement the Object interface + + + + + + + + + + +### func (\*ObjectMeta) [GetCreated](/src/target/meta.go?s=1334:1380#L58) +``` go +func (o *ObjectMeta) GetCreated() *metav1.Time +``` +GetCreated returns when the Object was created + + + + +### func (\*ObjectMeta) [GetName](/src/target/meta.go?s=920:957#L38) +``` go +func (o *ObjectMeta) GetName() string +``` +GetName returns the name of the Object + + + + +### func (\*ObjectMeta) [GetUID](/src/target/meta.go?s=1119:1155#L48) +``` go +func (o *ObjectMeta) GetUID() string +``` +GetUID returns the UID of the Object + + + + +### func (\*ObjectMeta) [SetCreated](/src/target/meta.go?s=1454:1501#L63) +``` go +func (o *ObjectMeta) SetCreated(t *metav1.Time) +``` +SetCreated returns when the Object was created + + + + +### func (\*ObjectMeta) [SetName](/src/target/meta.go?s=1017:1058#L43) +``` go +func (o *ObjectMeta) SetName(name string) +``` +SetName sets the name of the Object + + + + +### func (\*ObjectMeta) [SetUID](/src/target/meta.go?s=1221:1260#L53) +``` go +func (o *ObjectMeta) SetUID(uid string) +``` +SetUID sets the UID of the Object + + + + +## type [Size](/src/target/meta.go?s=2034:2073#L92) +``` go +type Size struct { + datasize.ByteSize +} + +``` +Size specifies a common unit for data sizes + + + + + + + +### func [NewSizeFromBytes](/src/target/meta.go?s=2296:2336#L107) +``` go +func NewSizeFromBytes(bytes uint64) Size +``` + +### func [NewSizeFromSectors](/src/target/meta.go?s=2387:2431#L113) +``` go +func NewSizeFromSectors(sectors uint64) Size +``` + +### func [NewSizeFromString](/src/target/meta.go?s=2177:2225#L101) +``` go +func NewSizeFromString(str string) (Size, error) +``` + + + + +### func (Size) [Add](/src/target/meta.go?s=2891:2925#L135) +``` go +func (s Size) Add(other Size) Size +``` +Add returns a copy, does not modify the receiver + + + + +### func (\*Size) [Int64](/src/target/meta.go?s=2780:2808#L130) +``` go +func (s *Size) Int64() int64 +``` +Int64 returns the byte size as int64 + + + + +### func (\*Size) [MarshalJSON](/src/target/meta.go?s=3177:3221#L156) +``` go +func (s *Size) MarshalJSON() ([]byte, error) +``` + + + +### func (Size) [Max](/src/target/meta.go?s=3074:3108#L148) +``` go +func (s Size) Max(other Size) Size +``` + + + +### func (Size) [Min](/src/target/meta.go?s=2971:3005#L140) +``` go +func (s Size) Min(other Size) Size +``` + + + +### func (\*Size) [Sectors](/src/target/meta.go?s=2497:2528#L119) +``` go +func (s *Size) Sectors() uint64 +``` + + + +### func (\*Size) [String](/src/target/meta.go?s=2661:2691#L124) +``` go +func (s *Size) String() string +``` +Override ByteSize's default string implementation which results in something similar to HR() + + + + +### func (\*Size) [UnmarshalJSON](/src/target/meta.go?s=3260:3304#L160) +``` go +func (s *Size) UnmarshalJSON(b []byte) error +``` + + + +## type [UID](/src/target/meta.go?s=1867:1882#L84) +``` go +type UID string +``` +UID represents an unique ID for a type + + + + + + + + + + +### func (UID) [String](/src/target/meta.go?s=1935:1963#L87) +``` go +func (u UID) String() string +``` +String returns the UID in string representation + + + + + + + + +- - - +Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)