Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update descriptions in CRDs #613

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs: update descriptions in CRDs #613

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ff9ed96
Formatting and wording edits in crds descriptions
maxinsky Dec 28, 2024
6fb1f29
Apply suggestions from code review
z9r5 Dec 31, 2024
058d59e
Apply suggestions from code review
maxinsky Jan 10, 2025
6ac2ce6
Additional edits
maxinsky Jan 10, 2025
3df8fc7
Minor documentation changes
TatikoRin Aug 13, 2024
15de849
Minor documentation changes
z9r5 Jan 10, 2025
651c25e
Edit sources for task-generated YAMLs
maxinsky Jan 14, 2025
e395dcb
Minor edits in resource descriptions
maxinsky Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions api/core/v1alpha2/cluster_virtual_image.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ const (
ClusterVirtualImageResource = "clustervirtualimages"
)

// Describes a virtual disk image that can be used as a data source for new `VirtualDisks` or an installation image (iso) to be mounted in `Virtuals` directly. This resource type is available for all namespaces in the cluster.
// Describes a virtual disk image that can be used as a data source for new VirtualDisks or an installation image (iso) to be mounted in VirtualMachines directly. This resource type is available for all namespaces in the cluster.
//
// > This resource cannot be modified once it has been created.
//
// A container image is created under the hood of this resource, which is stored in a dedicated deckhouse virtualization container registry (DVCR).
// With this resource in the cluster, a container image is created and stored in a dedicated Deckhouse Virtualization Container Registry (DVCR).
//
// +kubebuilder:object:root=true
// +kubebuilder:metadata:labels={heritage=deckhouse,module=virtualization,backup.deckhouse.io/cluster-config=true}
Expand Down Expand Up @@ -58,56 +58,56 @@ type ClusterVirtualImage struct {
}

// ClusterVirtualImageList provides the needed parameters
// to do request a list of ClusterVirtualImages from the system.
// for requesting a list of ClusterVirtualImages from the system.
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
type ClusterVirtualImageList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata"`

// Items provides a list of CDIs
// Items provides a list of CVIs.
Items []ClusterVirtualImage `json:"items"`
}

type ClusterVirtualImageSpec struct {
DataSource ClusterVirtualImageDataSource `json:"dataSource"`
}

// An origin of the image.
// +kubebuilder:validation:XValidation:rule="self.type == 'HTTP' ? has(self.http) && !has(self.containerImage) && !has(self.objectRef) : true",message="HTTP requires http and cannot have ContainerImage or ObjectRef"
// +kubebuilder:validation:XValidation:rule="self.type == 'ContainerImage' ? has(self.containerImage) && !has(self.http) && !has(self.objectRef) : true",message="ContainerImage requires containerImage and cannot have HTTP or ObjectRef"
// +kubebuilder:validation:XValidation:rule="self.type == 'ObjectRef' ? has(self.objectRef) && !has(self.http) && !has(self.containerImage) : true",message="ObjectRef requires objectRef and cannot have HTTP or ContainerImage"
// Origin of the image.
// +kubebuilder:validation:XValidation:rule="self.type == 'HTTP' ? has(self.http) && !has(self.containerImage) && !has(self.objectRef) : true",message="HTTP requires http and cannot have ContainerImage or ObjectRef."
// +kubebuilder:validation:XValidation:rule="self.type == 'ContainerImage' ? has(self.containerImage) && !has(self.http) && !has(self.objectRef) : true",message="ContainerImage requires containerImage and cannot have HTTP or ObjectRef."
// +kubebuilder:validation:XValidation:rule="self.type == 'ObjectRef' ? has(self.objectRef) && !has(self.http) && !has(self.containerImage) : true",message="ObjectRef requires objectRef and cannot have HTTP or ContainerImage."
type ClusterVirtualImageDataSource struct {
Type DataSourceType `json:"type"`
HTTP *DataSourceHTTP `json:"http,omitempty"`
ContainerImage *ClusterVirtualImageContainerImage `json:"containerImage,omitempty"`
ObjectRef *ClusterVirtualImageObjectRef `json:"objectRef,omitempty"`
}

// Use an image stored in external container registry. Only TLS enabled registries are supported. Use caBundle field to provide custom CA chain if needed.
// Use an image stored in external container registry. Only registries with enabled TLS protocol are supported. To provide a custom Certificate Authority (CA) chain, use the `caBundle` field.
type ClusterVirtualImageContainerImage struct {
// The container registry address of an image.
// Path to the image in the container registry.
// +kubebuilder:example:="registry.example.com/images/slackware:15"
// +kubebuilder:validation:Pattern:=`^(?P<name>(?:(?P<domain>(?:(?:localhost|[\w-]+(?:\.[\w-]+)+)(?::\d+)?)|[\w]+:\d+)/)?(?P<image>[a-z0-9_.-]+(?:/[a-z0-9_.-]+)*))(?::(?P<tag>[\w][\w.-]{0,127}))?(?:@(?P<digest>[A-Za-z][A-Za-z0-9]*(?:[+.-_][A-Za-z][A-Za-z0-9]*)*:[0-9a-fA-F]{32,}))?$`
Image string `json:"image"`
ImagePullSecret ImagePullSecret `json:"imagePullSecret,omitempty"`
// The CA chain in base64 format to verify the container registry.
// CA chain in Base64 format to verify the container registry.
// +kubebuilder:example:="YWFhCg=="
CABundle []byte `json:"caBundle,omitempty"`
}

// Use an existing `VirtualImage`, `ClusterVirtualImage` or `VirtualDisk` to create an image.
// Use an existing VirtualImage, ClusterVirtualImage, or VirtualDisk resource to create an image.
//
// +kubebuilder:validation:XValidation:rule="self.kind == 'VirtualImage' || self.kind == 'VirtualDisk' ? has(self.__namespace__) && size(self.__namespace__) > 0 : true",message="The namespace is required for VirtualDisk and VirtualImage"
// +kubebuilder:validation:XValidation:rule="self.kind == 'VirtualImage' || self.kind == 'VirtualDisk' ? has(self.__namespace__) && size(self.__namespace__) > 0 : true",message="The namespace is required for VirtualDisk and VirtualImage."
// +kubebuilder:validation:XValidation:rule="self.kind == 'VirtualImage' || self.kind == 'VirtualDisk' ? has(self.__namespace__) && size(self.__namespace__) < 64 : true",message="The namespace must be no longer than 63 characters."
type ClusterVirtualImageObjectRef struct {
Kind ClusterVirtualImageObjectRefKind `json:"kind"`
// A name of existing `VirtualImage`, `ClusterVirtualImage` or `VirtualDisk`.
// Name of the existing VirtualImage, ClusterVirtualImage, or VirtualDisk resource.
Name string `json:"name"`
// A namespace where `VirtualImage` or `VirtualDisk` is located.
// Namespace where the VirtualImage or VirtualDisk resource is located.
Namespace string `json:"namespace,omitempty"`
}

// A kind of existing `VirtualImage`, `ClusterVirtualImage` or `VirtualDisk`.
// Kind of the existing VirtualImage, ClusterVirtualImage, or VirtualDisk resource.
// +kubebuilder:validation:Enum:={ClusterVirtualImage,VirtualImage,VirtualDisk}
type ClusterVirtualImageObjectRefKind string

Expand All @@ -120,30 +120,30 @@ const (
type ClusterVirtualImageStatus struct {
// Image download speed from an external source. Appears only during the `Provisioning` phase.
DownloadSpeed *StatusSpeed `json:"downloadSpeed,omitempty"`
// Discovered sizes of the image.
// Discovered image size data.
Size ImageStatusSize `json:"size,omitempty"`
// Discovered format of the image.
// Discovered image format.
Format string `json:"format,omitempty"`
// Whether the image is a format that is supposed to be mounted as a cdrom, such as iso and so on.
// Defines whether the image is in a format that needs to be mounted as a CD-ROM drive, such as iso and so on.
CDROM bool `json:"cdrom,omitempty"`
// Current status of `ClusterVirtualImage` resource:
// * Pending - The resource has been created and is on a waiting queue.
// * Provisioning - The process of resource creation (copying/downloading/building the image) is in progress.
// * WaitForUserUpload - Waiting for the user to upload the image. The endpoint to upload the image is specified in `.status.uploadCommand`.
// * Ready - The resource is created and ready to use.
// * Failed - There was a problem when creating a resource.
// * Terminating - The process of resource deletion is in progress.
// Current status of the ClusterVirtualImage resource:
// * `Pending`: The resource has been created and is on a waiting queue.
// * `Provisioning`: The resource is being created: copying, downloading, or building of the image is in progress.
// * `WaitForUserUpload`: Waiting for the user to upload the image. The endpoint to upload the image is specified in `.status.uploadCommand`.
// * `Ready`: The resource has been created and is ready to use.
// * `Failed`: There was an error when creating the resource.
// * `Terminating`: The resource is being deleted.
// +kubebuilder:validation:Enum:={Pending,Provisioning,WaitForUserUpload,Ready,Failed,Terminating}
Phase ImagePhase `json:"phase,omitempty"`
// Progress of copying an image from source to DVCR. Appears only during the `Provisioning' phase.
// Progress of copying an image from the source to DVCR. Appears only during the `Provisioning' phase.
Progress string `json:"progress,omitempty"`
// The UID of the source (`VirtualImage`, `ClusterVirtualImage` or `VirtualDisk`) used when creating the cluster virtual image.
// UID of the source (VirtualImage, ClusterVirtualImage, or VirtualDisk) used when creating the cluster virtual image.
SourceUID *types.UID `json:"sourceUID,omitempty"`
// The latest available observations of an object's current state.
Conditions []metav1.Condition `json:"conditions,omitempty"`
// The generation last processed by the controller.
// Resource generation last processed by the controller.
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
// Deprecated. Use imageUploadURLs instead.
// Deprecated. Use `imageUploadURLs` instead.
UploadCommand string `json:"uploadCommand,omitempty"`
ImageUploadURLs *ImageUploadURLs `json:"imageUploadURLs,omitempty"`
Target ClusterVirtualImageStatusTarget `json:"target,omitempty"`
Expand Down
32 changes: 16 additions & 16 deletions api/core/v1alpha2/data_source.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,41 +16,41 @@ limitations under the License.

package v1alpha2

// Fill the image with data from some external url. Supported schemas are:
// Fill the image with data from an external URL. The following schemas are supported:
//
// * http
// * https
// * HTTP
// * HTTPS
//
// For https schema there is an option to skip TLS verification.
// For HTTPS schema, there is an option to skip the TLS verification.
type DataSourceHTTP struct {
// A checksum of the file, provided by the url, to verify if it was downloaded correctly or wasn't changed. The file should match all specified checksums.
// Checksum to verify integrity and consistency of the downloaded file. The file must match all specified checksums.
Checksum *Checksum `json:"checksum,omitempty"`
// The http url with an image. The following formats are supported:
// URL of the file for creating an image. The following file formats are supported:
// * qcow2
// * vmdk
// * vdi
// * iso
// * raw
// these formats can also be compressed with the following formats:
// The file can be compressed into an archive in one of the following formats:
// * gz
// * xz
// +kubebuilder:example:="https://mirror.example.com/images/slackware-15.qcow.gz"
// +kubebuilder:validation:Pattern=`^http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[$-_@.&+]|[!*\(\),]|(?:%[0-9a-fA-F][0-9a-fA-F]))+$`
URL string `json:"url"`
// The CA chain in base64 format to verify the url.
// CA chain in Base64 format to verify the URL.
// +kubebuilder:example:="YWFhCg=="
CABundle []byte `json:"caBundle,omitempty"`
}

type ImagePullSecret struct {
// A name of the secret containing registry credentials.
// Name of the secret keeping container registry credentials.
Name string `json:"name,omitempty"`
// A namespace where imagePullSecret is located.
// Namespace where `imagePullSecret` is located.
Namespace string `json:"namespace,omitempty"`
}

type ImagePullSecretName struct {
// A name of the secret containing registry credentials which must be located in the same namespace.
// Name of the secret keeping container registry credentials, which must be located in the same namespace.
Name string `json:"name,omitempty"`
}

Expand All @@ -67,12 +67,12 @@ type Checksum struct {
SHA256 string `json:"sha256,omitempty"`
}

// The type of an origin of the image. Options are:
// The following image sources are available for creating an image:
//
// * `HTTP` — create an image from a file published on http/https service at a given url
// * `ContainerImage` — create the image from image stored in container registry.
// * `ObjectRef` — fill the disk from another existing resource.
// * `Upload` — fill the image with data, uploaded by user via the special interface.
// * `HTTP`: From a file published on an HTTP/HTTPS service at a given URL.
// * `ContainerImage`: From another image stored in a container registry.
// * `ObjectRef`: From an existing resource.
// * `Upload`: From data uploaded by the user via a special interface.
//
// +kubebuilder:validation:Enum:={HTTP,ContainerImage,ObjectRef,Upload}
type DataSourceType string
Expand Down
Loading
Loading