From e414173da545f295da56ebf218fd01d81b35f733 Mon Sep 17 00:00:00 2001 From: madhav bhargava Date: Mon, 11 Nov 2024 09:45:12 +0530 Subject: [PATCH] switched to using elastic crd-ref-docs which generates a proper md --- Makefile | 8 +- docs/api-reference/etcd-druid-api.md | 679 +++++++++++++++++++++++++++ hack/api-reference/config.yaml | 8 + hack/demo/etcd-druid-demo.tape | 194 -------- hack/tools.mk | 8 +- mkdocs.yml | 2 + 6 files changed, 701 insertions(+), 198 deletions(-) create mode 100644 docs/api-reference/etcd-druid-api.md create mode 100644 hack/api-reference/config.yaml delete mode 100644 hack/demo/etcd-druid-demo.tape diff --git a/Makefile b/Makefile index 3eb06ea50..4b6b1c3f4 100644 --- a/Makefile +++ b/Makefile @@ -37,10 +37,14 @@ manifests: $(VGOPATH) $(CONTROLLER_GEN) @find "$(REPO_ROOT)/config/crd/bases" -name "*.yaml" -exec cp '{}' "$(REPO_ROOT)/charts/druid/charts/crds/templates/" \; @controller-gen rbac:roleName=manager-role paths="./internal/controller/..." +.PHONY: generate-api-docs +generate-api-docs: $(CRD_REF_DOCS) + @crd-ref-docs --source-path "$(REPO_ROOT)/api" --config "$(HACK_DIR)/api-reference/config.yaml" --output-path "$(REPO_ROOT)/docs/api-reference/etcd-druid-api.md" --renderer markdown + # Generate code .PHONY: generate -generate: manifests $(CONTROLLER_GEN) $(GOIMPORTS) $(MOCKGEN) - @go generate "$(REPO_ROOT)/internal/..." +generate: manifests generate-api-docs $(CONTROLLER_GEN) $(GOIMPORTS) $(MOCKGEN) + @go generate "$(REPO_ROOT)/..." @"$(HACK_DIR)/update-codegen.sh" # Rules for verification, formatting, linting and cleaning diff --git a/docs/api-reference/etcd-druid-api.md b/docs/api-reference/etcd-druid-api.md new file mode 100644 index 000000000..14824674a --- /dev/null +++ b/docs/api-reference/etcd-druid-api.md @@ -0,0 +1,679 @@ +# API Reference + +## Packages +- [druid.gardener.cloud/v1alpha1](#druidgardenercloudv1alpha1) + + +## druid.gardener.cloud/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the druid v1alpha1 API group + +### Resource Types +- [Etcd](#etcd) +- [EtcdCopyBackupsTask](#etcdcopybackupstask) + + + +#### BackupSpec + + + +BackupSpec defines parameters associated with the full and delta snapshots of etcd. + + + +_Appears in:_ +- [EtcdSpec](#etcdspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `port` _integer_ | Port define the port on which etcd-backup-restore server will be exposed. | | | +| `tls` _[TLSConfig](#tlsconfig)_ | | | | +| `image` _string_ | Image defines the etcd container image and tag | | | +| `store` _[StoreSpec](#storespec)_ | Store defines the specification of object store provider for storing backups. | | | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#resourcerequirements-v1-core)_ | Resources defines compute Resources required by backup-restore container.
More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ | | | +| `compactionResources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#resourcerequirements-v1-core)_ | CompactionResources defines compute Resources required by compaction job.
More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ | | | +| `fullSnapshotSchedule` _string_ | FullSnapshotSchedule defines the cron standard schedule for full snapshots. | | | +| `garbageCollectionPolicy` _[GarbageCollectionPolicy](#garbagecollectionpolicy)_ | GarbageCollectionPolicy defines the policy for garbage collecting old backups | | Enum: [Exponential LimitBased]
| +| `maxBackupsLimitBasedGC` _integer_ | MaxBackupsLimitBasedGC defines the maximum number of Full snapshots to retain in Limit Based GarbageCollectionPolicy
All full snapshots beyond this limit will be garbage collected. | | | +| `garbageCollectionPeriod` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | GarbageCollectionPeriod defines the period for garbage collecting old backups | | | +| `deltaSnapshotPeriod` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | DeltaSnapshotPeriod defines the period after which delta snapshots will be taken | | | +| `deltaSnapshotMemoryLimit` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#quantity-resource-api)_ | DeltaSnapshotMemoryLimit defines the memory limit after which delta snapshots will be taken | | | +| `deltaSnapshotRetentionPeriod` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | DeltaSnapshotRetentionPeriod defines the duration for which delta snapshots will be retained, excluding the latest snapshot set.
The value should be a string formatted as a duration (e.g., '1s', '2m', '3h', '4d') | | Pattern: `^([0-9][0-9]*([.][0-9]+)?(s\|m\|h\|d))+$`
Type: string
| +| `compression` _[CompressionSpec](#compressionspec)_ | SnapshotCompression defines the specification for compression of Snapshots. | | | +| `enableProfiling` _boolean_ | EnableProfiling defines if profiling should be enabled for the etcd-backup-restore-sidecar | | | +| `etcdSnapshotTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | EtcdSnapshotTimeout defines the timeout duration for etcd FullSnapshot operation | | | +| `leaderElection` _[LeaderElectionSpec](#leaderelectionspec)_ | LeaderElection defines parameters related to the LeaderElection configuration. | | | + + +#### ClientService + + + +ClientService defines the parameters of the client service that a user can specify + + + +_Appears in:_ +- [EtcdConfig](#etcdconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `annotations` _object (keys:string, values:string)_ | Annotations specify the annotations that should be added to the client service | | | +| `labels` _object (keys:string, values:string)_ | Labels specify the labels that should be added to the client service | | | + + +#### CompactionMode + +_Underlying type:_ _string_ + +CompactionMode defines the auto-compaction-mode: 'periodic' or 'revision'. +'periodic' for duration based retention and 'revision' for revision number based retention. + +_Validation:_ +- Enum: [periodic revision] + +_Appears in:_ +- [SharedConfig](#sharedconfig) + +| Field | Description | +| --- | --- | +| `periodic` | Periodic is a constant to set auto-compaction-mode 'periodic' for duration based retention.
| +| `revision` | Revision is a constant to set auto-compaction-mode 'revision' for revision number based retention.
| + + +#### CompressionPolicy + +_Underlying type:_ _string_ + +CompressionPolicy defines the type of policy for compression of snapshots. + +_Validation:_ +- Enum: [gzip lzw zlib] + +_Appears in:_ +- [CompressionSpec](#compressionspec) + +| Field | Description | +| --- | --- | +| `gzip` | GzipCompression is constant for gzip compression policy.
| +| `lzw` | LzwCompression is constant for lzw compression policy.
| +| `zlib` | ZlibCompression is constant for zlib compression policy.
| + + +#### CompressionSpec + + + +CompressionSpec defines parameters related to compression of Snapshots(full as well as delta). + + + +_Appears in:_ +- [BackupSpec](#backupspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enabled` _boolean_ | | | | +| `policy` _[CompressionPolicy](#compressionpolicy)_ | | | Enum: [gzip lzw zlib]
| + + +#### Condition + + + +Condition holds the information about the state of a resource. + + + +_Appears in:_ +- [EtcdCopyBackupsTaskStatus](#etcdcopybackupstaskstatus) +- [EtcdStatus](#etcdstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[ConditionType](#conditiontype)_ | Type of the Etcd condition. | | | +| `status` _[ConditionStatus](#conditionstatus)_ | Status of the condition, one of True, False, Unknown. | | | +| `lastTransitionTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#time-v1-meta)_ | Last time the condition transitioned from one status to another. | | | +| `lastUpdateTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#time-v1-meta)_ | Last time the condition was updated. | | | +| `reason` _string_ | The reason for the condition's last transition. | | | +| `message` _string_ | A human-readable message indicating details about the transition. | | | + + +#### ConditionStatus + +_Underlying type:_ _string_ + +ConditionStatus is the status of a condition. + + + +_Appears in:_ +- [Condition](#condition) + +| Field | Description | +| --- | --- | +| `True` | ConditionTrue means a resource is in the condition.
| +| `False` | ConditionFalse means a resource is not in the condition.
| +| `Unknown` | ConditionUnknown means Gardener can't decide if a resource is in the condition or not.
| +| `Progressing` | ConditionProgressing means the condition was seen true, failed but stayed within a predefined failure threshold.
In the future, we could add other intermediate conditions, e.g. ConditionDegraded.
| +| `ConditionCheckError` | ConditionCheckError is a constant for a reason in condition.
| + + +#### ConditionType + +_Underlying type:_ _string_ + +ConditionType is the type of condition. + + + +_Appears in:_ +- [Condition](#condition) + +| Field | Description | +| --- | --- | +| `Ready` | ConditionTypeReady is a constant for a condition type indicating that the etcd cluster is ready.
| +| `AllMembersReady` | ConditionTypeAllMembersReady is a constant for a condition type indicating that all members of the etcd cluster are ready.
| +| `BackupReady` | ConditionTypeBackupReady is a constant for a condition type indicating that the etcd backup is ready.
| +| `DataVolumesReady` | ConditionTypeDataVolumesReady is a constant for a condition type indicating that the etcd data volumes are ready.
| +| `Succeeded` | EtcdCopyBackupsTaskSucceeded is a condition type indicating that a EtcdCopyBackupsTask has succeeded.
| +| `Failed` | EtcdCopyBackupsTaskFailed is a condition type indicating that a EtcdCopyBackupsTask has failed.
| + + +#### CrossVersionObjectReference + + + +CrossVersionObjectReference contains enough information to let you identify the referred resource. + + + +_Appears in:_ +- [EtcdStatus](#etcdstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | Kind of the referent | | | +| `name` _string_ | Name of the referent | | | +| `apiVersion` _string_ | API version of the referent | | | + + +#### ErrorCode + +_Underlying type:_ _string_ + +ErrorCode is a string alias representing an error code that identifies an error. + + + +_Appears in:_ +- [LastError](#lasterror) + + + +#### Etcd + + + +Etcd is the Schema for the etcds API + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `druid.gardener.cloud/v1alpha1` | | | +| `kind` _string_ | `Etcd` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[EtcdSpec](#etcdspec)_ | | | | +| `status` _[EtcdStatus](#etcdstatus)_ | | | | + + +#### EtcdConfig + + + +EtcdConfig defines the configuration for the etcd cluster to be deployed. + + + +_Appears in:_ +- [EtcdSpec](#etcdspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `quota` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#quantity-resource-api)_ | Quota defines the etcd DB quota. | | | +| `defragmentationSchedule` _string_ | DefragmentationSchedule defines the cron standard schedule for defragmentation of etcd. | | | +| `serverPort` _integer_ | | | | +| `clientPort` _integer_ | | | | +| `image` _string_ | Image defines the etcd container image and tag | | | +| `authSecretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretreference-v1-core)_ | | | | +| `metrics` _[MetricsLevel](#metricslevel)_ | Metrics defines the level of detail for exported metrics of etcd, specify 'extensive' to include histogram metrics. | | Enum: [basic extensive]
| +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#resourcerequirements-v1-core)_ | Resources defines the compute Resources required by etcd container.
More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ | | | +| `clientUrlTls` _[TLSConfig](#tlsconfig)_ | ClientUrlTLS contains the ca, server TLS and client TLS secrets for client communication to ETCD cluster | | | +| `peerUrlTls` _[TLSConfig](#tlsconfig)_ | PeerUrlTLS contains the ca and server TLS secrets for peer communication within ETCD cluster
Currently, PeerUrlTLS does not require client TLS secrets for gardener implementation of ETCD cluster. | | | +| `etcdDefragTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | EtcdDefragTimeout defines the timeout duration for etcd defrag call | | | +| `heartbeatDuration` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | HeartbeatDuration defines the duration for members to send heartbeats. The default value is 10s. | | | +| `clientService` _[ClientService](#clientservice)_ | ClientService defines the parameters of the client service that a user can specify | | | + + +#### EtcdCopyBackupsTask + + + +EtcdCopyBackupsTask is a task for copying etcd backups from a source to a target store. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `druid.gardener.cloud/v1alpha1` | | | +| `kind` _string_ | `EtcdCopyBackupsTask` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[EtcdCopyBackupsTaskSpec](#etcdcopybackupstaskspec)_ | | | | +| `status` _[EtcdCopyBackupsTaskStatus](#etcdcopybackupstaskstatus)_ | | | | + + +#### EtcdCopyBackupsTaskSpec + + + +EtcdCopyBackupsTaskSpec defines the parameters for the copy backups task. + + + +_Appears in:_ +- [EtcdCopyBackupsTask](#etcdcopybackupstask) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `sourceStore` _[StoreSpec](#storespec)_ | SourceStore defines the specification of the source object store provider for storing backups. | | | +| `targetStore` _[StoreSpec](#storespec)_ | TargetStore defines the specification of the target object store provider for storing backups. | | | +| `maxBackupAge` _integer_ | MaxBackupAge is the maximum age in days that a backup must have in order to be copied.
By default all backups will be copied. | | | +| `maxBackups` _integer_ | MaxBackups is the maximum number of backups that will be copied starting with the most recent ones. | | | +| `waitForFinalSnapshot` _[WaitForFinalSnapshotSpec](#waitforfinalsnapshotspec)_ | WaitForFinalSnapshot defines the parameters for waiting for a final full snapshot before copying backups. | | | + + +#### EtcdCopyBackupsTaskStatus + + + +EtcdCopyBackupsTaskStatus defines the observed state of the copy backups task. + + + +_Appears in:_ +- [EtcdCopyBackupsTask](#etcdcopybackupstask) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `conditions` _[Condition](#condition) array_ | Conditions represents the latest available observations of an object's current state. | | | +| `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this resource. | | | +| `lastError` _string_ | LastError represents the last occurred error. | | | + + +#### EtcdMemberConditionStatus + +_Underlying type:_ _string_ + +EtcdMemberConditionStatus is the status of an etcd cluster member. + + + +_Appears in:_ +- [EtcdMemberStatus](#etcdmemberstatus) + +| Field | Description | +| --- | --- | +| `Ready` | EtcdMemberStatusReady indicates that the etcd member is ready.
| +| `NotReady` | EtcdMemberStatusNotReady indicates that the etcd member is not ready.
| +| `Unknown` | EtcdMemberStatusUnknown indicates that the status of the etcd member is unknown.
| + + +#### EtcdMemberStatus + + + +EtcdMemberStatus holds information about etcd cluster membership. + + + +_Appears in:_ +- [EtcdStatus](#etcdstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the etcd member. It is the name of the backing `Pod`. | | | +| `id` _string_ | ID is the ID of the etcd member. | | | +| `role` _[EtcdRole](#etcdrole)_ | Role is the role in the etcd cluster, either `Leader` or `Member`. | | | +| `status` _[EtcdMemberConditionStatus](#etcdmemberconditionstatus)_ | Status of the condition, one of True, False, Unknown. | | | +| `reason` _string_ | The reason for the condition's last transition. | | | +| `lastTransitionTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#time-v1-meta)_ | LastTransitionTime is the last time the condition's status changed. | | | + + +#### EtcdRole + +_Underlying type:_ _string_ + +EtcdRole is the role of an etcd cluster member. + + + +_Appears in:_ +- [EtcdMemberStatus](#etcdmemberstatus) + +| Field | Description | +| --- | --- | +| `Leader` | EtcdRoleLeader describes the etcd role `Leader`.
| +| `Member` | EtcdRoleMember describes the etcd role `Member`.
| + + +#### EtcdSpec + + + +EtcdSpec defines the desired state of Etcd + + + +_Appears in:_ +- [Etcd](#etcd) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `selector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#labelselector-v1-meta)_ | selector is a label query over pods that should match the replica count.
It must match the pod template's labels.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors | | | +| `labels` _object (keys:string, values:string)_ | | | | +| `annotations` _object (keys:string, values:string)_ | | | | +| `etcd` _[EtcdConfig](#etcdconfig)_ | | | | +| `backup` _[BackupSpec](#backupspec)_ | | | | +| `sharedConfig` _[SharedConfig](#sharedconfig)_ | | | | +| `schedulingConstraints` _[SchedulingConstraints](#schedulingconstraints)_ | | | | +| `replicas` _integer_ | | | | +| `priorityClassName` _string_ | PriorityClassName is the name of a priority class that shall be used for the etcd pods. | | | +| `storageClass` _string_ | StorageClass defines the name of the StorageClass required by the claim.
More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 | | | +| `storageCapacity` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#quantity-resource-api)_ | StorageCapacity defines the size of persistent volume. | | | +| `volumeClaimTemplate` _string_ | VolumeClaimTemplate defines the volume claim template to be created | | | + + +#### EtcdStatus + + + +EtcdStatus defines the observed state of Etcd. + + + +_Appears in:_ +- [Etcd](#etcd) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this resource. | | | +| `etcd` _[CrossVersionObjectReference](#crossversionobjectreference)_ | | | | +| `conditions` _[Condition](#condition) array_ | Conditions represents the latest available observations of an etcd's current state. | | | +| `serviceName` _string_ | ServiceName is the name of the etcd service.
Deprecated: this field will be removed in the future. | | | +| `lastError` _string_ | LastError represents the last occurred error.
Deprecated: Use LastErrors instead. | | | +| `lastErrors` _[LastError](#lasterror) array_ | LastErrors captures errors that occurred during the last operation. | | | +| `lastOperation` _[LastOperation](#lastoperation)_ | LastOperation indicates the last operation performed on this resource. | | | +| `clusterSize` _integer_ | Cluster size is the current size of the etcd cluster.
Deprecated: this field will not be populated with any value and will be removed in the future. | | | +| `currentReplicas` _integer_ | CurrentReplicas is the current replica count for the etcd cluster. | | | +| `replicas` _integer_ | Replicas is the replica count of the etcd cluster. | | | +| `readyReplicas` _integer_ | ReadyReplicas is the count of replicas being ready in the etcd cluster. | | | +| `ready` _boolean_ | Ready is `true` if all etcd replicas are ready. | | | +| `updatedReplicas` _integer_ | UpdatedReplicas is the count of updated replicas in the etcd cluster.
Deprecated: this field will be removed in the future. | | | +| `labelSelector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#labelselector-v1-meta)_ | LabelSelector is a label query over pods that should match the replica count.
It must match the pod template's labels.
Deprecated: this field will be removed in the future. | | | +| `members` _[EtcdMemberStatus](#etcdmemberstatus) array_ | Members represents the members of the etcd cluster | | | +| `peerUrlTLSEnabled` _boolean_ | PeerUrlTLSEnabled captures the state of peer url TLS being enabled for the etcd member(s) | | | + + +#### GarbageCollectionPolicy + +_Underlying type:_ _string_ + +GarbageCollectionPolicy defines the type of policy for snapshot garbage collection. + +_Validation:_ +- Enum: [Exponential LimitBased] + +_Appears in:_ +- [BackupSpec](#backupspec) + + + +#### LastError + + + +LastError stores details of the most recent error encountered for a resource. + + + +_Appears in:_ +- [EtcdStatus](#etcdstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `code` _[ErrorCode](#errorcode)_ | Code is an error code that uniquely identifies an error. | | | +| `description` _string_ | Description is a human-readable message indicating details of the error. | | | +| `observedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#time-v1-meta)_ | ObservedAt is the time the error was observed. | | | + + +#### LastOperation + + + +LastOperation holds the information on the last operation done on the Etcd resource. + + + +_Appears in:_ +- [EtcdStatus](#etcdstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[LastOperationType](#lastoperationtype)_ | Type is the type of last operation. | | | +| `state` _[LastOperationState](#lastoperationstate)_ | State is the state of the last operation. | | | +| `description` _string_ | Description describes the last operation. | | | +| `runID` _string_ | RunID correlates an operation with a reconciliation run.
Every time an Etcd resource is reconciled (barring status reconciliation which is periodic), a unique ID is
generated which can be used to correlate all actions done as part of a single reconcile run. Capturing this
as part of LastOperation aids in establishing this correlation. This further helps in also easily filtering
reconcile logs as all structured logs in a reconciliation run should have the `runID` referenced. | | | +| `lastUpdateTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#time-v1-meta)_ | LastUpdateTime is the time at which the operation was last updated. | | | + + +#### LastOperationState + +_Underlying type:_ _string_ + +LastOperationState is a string alias representing the state of the last operation. + + + +_Appears in:_ +- [LastOperation](#lastoperation) + +| Field | Description | +| --- | --- | +| `Processing` | LastOperationStateProcessing indicates that an operation is in progress.
| +| `Succeeded` | LastOperationStateSucceeded indicates that an operation has completed successfully.
| +| `Error` | LastOperationStateError indicates that an operation is completed with errors and will be retried.
| +| `Requeue` | LastOperationStateRequeue indicates that an operation is not completed and either due to an error or unfulfilled conditions will be retried.
| + + +#### LastOperationType + +_Underlying type:_ _string_ + +LastOperationType is a string alias representing type of the last operation. + + + +_Appears in:_ +- [LastOperation](#lastoperation) + +| Field | Description | +| --- | --- | +| `Create` | LastOperationTypeCreate indicates that the last operation was a creation of a new Etcd resource.
| +| `Reconcile` | LastOperationTypeReconcile indicates that the last operation was a reconciliation of the spec of an Etcd resource.
| +| `Delete` | LastOperationTypeDelete indicates that the last operation was a deletion of an existing Etcd resource.
| + + +#### LeaderElectionSpec + + + +LeaderElectionSpec defines parameters related to the LeaderElection configuration. + + + +_Appears in:_ +- [BackupSpec](#backupspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `reelectionPeriod` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | ReelectionPeriod defines the Period after which leadership status of corresponding etcd is checked. | | | +| `etcdConnectionTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | EtcdConnectionTimeout defines the timeout duration for etcd client connection during leader election. | | | + + +#### MetricsLevel + +_Underlying type:_ _string_ + +MetricsLevel defines the level 'basic' or 'extensive'. + +_Validation:_ +- Enum: [basic extensive] + +_Appears in:_ +- [EtcdConfig](#etcdconfig) + +| Field | Description | +| --- | --- | +| `basic` | Basic is a constant for metrics level basic.
| +| `extensive` | Extensive is a constant for metrics level extensive.
| + + +#### SchedulingConstraints + + + +SchedulingConstraints defines the different scheduling constraints that must be applied to the +pod spec in the etcd statefulset. +Currently supported constraints are Affinity and TopologySpreadConstraints. + + + +_Appears in:_ +- [EtcdSpec](#etcdspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#affinity-v1-core)_ | Affinity defines the various affinity and anti-affinity rules for a pod
that are honoured by the kube-scheduler. | | | +| `topologySpreadConstraints` _[TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#topologyspreadconstraint-v1-core) array_ | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains,
that are honoured by the kube-scheduler. | | | + + +#### SecretReference + + + +SecretReference defines a reference to a secret. + + + +_Appears in:_ +- [TLSConfig](#tlsconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | name is unique within a namespace to reference a secret resource. | | | +| `namespace` _string_ | namespace defines the space within which the secret name must be unique. | | | +| `dataKey` _string_ | DataKey is the name of the key in the data map containing the credentials. | | | + + +#### SharedConfig + + + +SharedConfig defines parameters shared and used by Etcd as well as backup-restore sidecar. + + + +_Appears in:_ +- [EtcdSpec](#etcdspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `autoCompactionMode` _[CompactionMode](#compactionmode)_ | AutoCompactionMode defines the auto-compaction-mode:'periodic' mode or 'revision' mode for etcd and embedded-etcd of backup-restore sidecar. | | Enum: [periodic revision]
| +| `autoCompactionRetention` _string_ | AutoCompactionRetention defines the auto-compaction-retention length for etcd as well as for embedded-etcd of backup-restore sidecar. | | | + + +#### StorageProvider + +_Underlying type:_ _string_ + +StorageProvider defines the type of object store provider for storing backups. + + + +_Appears in:_ +- [StoreSpec](#storespec) + + + +#### StoreSpec + + + +StoreSpec defines parameters related to ObjectStore persisting backups + + + +_Appears in:_ +- [BackupSpec](#backupspec) +- [EtcdCopyBackupsTaskSpec](#etcdcopybackupstaskspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `container` _string_ | Container is the name of the container the backup is stored at. | | | +| `prefix` _string_ | Prefix is the prefix used for the store. | | | +| `provider` _[StorageProvider](#storageprovider)_ | Provider is the name of the backup provider. | | | +| `secretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretreference-v1-core)_ | SecretRef is the reference to the secret which used to connect to the backup store. | | | + + +#### TLSConfig + + + +TLSConfig hold the TLS configuration details. + + + +_Appears in:_ +- [BackupSpec](#backupspec) +- [EtcdConfig](#etcdconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `tlsCASecretRef` _[SecretReference](#secretreference)_ | | | | +| `serverTLSSecretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretreference-v1-core)_ | | | | +| `clientTLSSecretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretreference-v1-core)_ | | | | + + +#### WaitForFinalSnapshotSpec + + + +WaitForFinalSnapshotSpec defines the parameters for waiting for a final full snapshot before copying backups. + + + +_Appears in:_ +- [EtcdCopyBackupsTaskSpec](#etcdcopybackupstaskspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enabled` _boolean_ | Enabled specifies whether to wait for a final full snapshot before copying backups. | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#duration-v1-meta)_ | Timeout is the timeout for waiting for a final full snapshot. When this timeout expires, the copying of backups
will be performed anyway. No timeout or 0 means wait forever. | | | + + diff --git a/hack/api-reference/config.yaml b/hack/api-reference/config.yaml new file mode 100644 index 000000000..287e5583b --- /dev/null +++ b/hack/api-reference/config.yaml @@ -0,0 +1,8 @@ +processor: + ignoreFields: + - "TypeMeta$" + ignoreTypes: + - "List$" + - "ParseError$" +render: + kubernetesVersion: 1.29 \ No newline at end of file diff --git a/hack/demo/etcd-druid-demo.tape b/hack/demo/etcd-druid-demo.tape deleted file mode 100644 index 09d0d9606..000000000 --- a/hack/demo/etcd-druid-demo.tape +++ /dev/null @@ -1,194 +0,0 @@ -# Instructions to generate the demo in .mp4 - -# Run: -# $ vhs etcd-druid-demo-realtime.tape - -# The generated video will be extremely long since the etcd cluster takes more than 2 minutes for all members to become Ready. - -# Use ffmpeg to speed up those 2 minutes. - -# ENSURE to run the first ffmpeg command with the flags in the specified order. -# If this is not done, the first few seconds of the demo would get skipped- -# since the order of the flags matters to find the first key frame in ffmpeg. -# Let the timestamp from which you want the playback to be sped up be H1:M1:S1, -# and the timestamp till which you want the playback to be sped up be H2:M2:S2, -# and the speed multiplier be SPEED, -# and the end time of the video be END. -# See the instructions in the .tape commands to identify parts - -# Run: -# $ cp etcd-druid-demo-realtime.mp4 input.mp4 -# $ ffmpeg -ss 0 -i input.mp4 -to H1:M1:S1 -c copy part1.mp4 -# $ ffmpeg -i input.mp4 -ss H1:M1:S1 -to 00:03:34 -c copy part2.mp4 -# $ ffmpeg -i input.mp4 -ss H2:M2:S2 -to END -c copy part3.mp4 -# $ ffmpeg -i part2.mp4 -filter:v "setpts=PTS/SPEED" part2_fast.mp4 -# $ cat << EOF > concat_list.txt -# file 'part1.mp4' -# file 'part2_fast.mp4' -# file 'part3.mp4' -# EOF -# $ ffmpeg -f concat -safe 0 -i concat_list.txt -c copy output.mp4 -# $ cp output.mp4 etcd-druid-demo.mp4 - -Output etcd-druid-demo-realtime.mp4 - -Require make -Require kubectl -Require tmux - -Set FontSize 16 -Set FontFamily "JetBrainsMono Nerd Font" -Set Width 1200 -Set Height 800 -Set WindowBar Colorful -Set CursorBlink true -Set TypingSpeed 75ms -Set WaitTimeout 30s - -# Begin part 1 - -Type "# Target any kubernetes cluster." -Sleep 130ms -Enter - -Type "# For this demo, we set up a local kubernetes cluster using kind, through the `kind-up` make target:" -Sleep 130ms -Enter - -Type "make kind-up" -Sleep 130ms -Enter -Wait - -Type "# Target this kind cluster by exporting KUBECONFIG and pointing it to the kubeconfig path of the kind cluster as shown above." -Sleep 130ms -Enter - -Type@50ms "export KUBECONFIG=hack/e2e-test/infrastructure/kind/kubeconfig" -Sleep 260ms -Enter - -Type "# We now have to install the CRDs and deploy etcd-druid." -Sleep 130ms -Enter - -Type "# The `deploy` make target installs CRDs, and creates a Deployment for etcd-druid in the default namespace:" -Sleep 130ms -Enter - -Type "make deploy" -Sleep 130ms -Enter -# a magic number that makes it work, things break otherwise -# Find this number with `$ time make deploy` and add some buffer -Sleep 12s - -Type "kubectl get pod # Checking the etcd-druid pod." -Sleep 130ms -Enter -Wait - -Type "# etcd-druid has now been deployed; and is ready to provision, reconcile, and monitor etcd clusters." -Sleep 130ms -Enter - -Type "# To create an etcd-cluster, just define an etcd CR and deploy it." -Sleep 3s -Enter - -# setup tmux -Hide - Type "tmux -f /dev/null -L test new-session -- bash" Enter - Type "tmux split-window -d -- bash && \" Enter - Type "tmux set status && \" Enter - Type 'tmux setw pane-border-style "fg=0" && \' Enter - Type 'tmux setw pane-active-border-style "fg=0"' Enter - Sleep 0.5 - Ctrl+L - Sleep 1 -Show - -# pane 1 - Type "# Using a pre-defined sample, config/samples/druid_v1alpha1_etcd.yaml, which creates a 3 member etcd-cluster." - Sleep 130ms - Enter - - Type "kubectl apply -f config/samples/druid_v1alpha1_etcd.yaml" - Sleep 130ms -# pane 1 - -# switch pane to 2 -Hide -Ctrl+B -Type o -Show - -# pane 2 - Type "# Meanwhile, keeping a watch on some of the resources being provisioned by etcd-druid:" - Enter - Sleep 130ms - Type "watch --interval 5 kubectl get etcd,sts,pod" - Enter - Sleep 130ms -# pane 2 - -# switch pane to 1 -Hide -Ctrl+B -Type o -Show - -# pane 1 - -# End part 1 - Enter - -# Begin part 2 - Sleep 210s -# End part 2 - -# Begin part 3 - - Type "# The etcd cluster is now ready." - Sleep 130ms - Enter - - Type "# Bringing the etcd cluster down is done by simply deleting the CR:" - Sleep 130ms - Enter - - Type "kubectl delete etcd etcd-test" - Sleep 130ms - Enter - Sleep 10s - - Type "# All resources provisioned by etcd-druid have been brought down, as can be seen below." - Sleep 130ms - Enter -# pane 1 - -# kill pane 2 -Hide -Ctrl+B -Type o -Ctrl+C -Type "tmux kill-pane" -Enter -Show - -Type "# Shutting down the kind cluster:" -Sleep 130ms -Enter - -Type "make kind-down" -Sleep 130ms -Enter -Sleep 5s - -Hide -Type "tmux kill-session" -Sleep 130ms -Enter -Show - -# End part 3 diff --git a/hack/tools.mk b/hack/tools.mk index 06a5f442b..ef9087368 100644 --- a/hack/tools.mk +++ b/hack/tools.mk @@ -24,6 +24,7 @@ GO_APIDIFF := $(TOOLS_BIN_DIR)/go-apidiff GOTESTFMT := $(TOOLS_BIN_DIR)/gotestfmt GOIMPORTS_REVISER := $(TOOLS_BIN_DIR)/goimports-reviser YQ := $(TOOLS_BIN_DIR)/yq +CRD_REF_DOCS := $(TOOLS_BIN_DIR)/crd-ref-docs # default tool versions SKAFFOLD_VERSION := v2.13.0 @@ -41,7 +42,7 @@ GO_APIDIFF_VERSION ?= v0.8.2 GOTESTFMT_VERSION ?= v2.5.0 GOIMPORTS_REVISER_VERSION ?= v3.6.5 YQ_VERSION ?= v4.44.3 - +CRD_REF_DOCS_VERSION ?= v0.1.0 export TOOLS_BIN_DIR := $(TOOLS_BIN_DIR) export PATH := $(abspath $(TOOLS_BIN_DIR)):$(PATH) @@ -116,4 +117,7 @@ $(GOTESTFMT): GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/gotesttools/gotestfmt/v2/cmd/gotestfmt@$(GOTESTFMT_VERSION) $(GOIMPORTS_REVISER): - GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/incu6us/goimports-reviser/v3@$(GOIMPORTS_REVISER_VERSION) \ No newline at end of file + GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/incu6us/goimports-reviser/v3@$(GOIMPORTS_REVISER_VERSION) + +$(CRD_REF_DOCS): + GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VERSION) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d4eac974e..921cdc4d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -92,6 +92,8 @@ nav: - Raising a PR: development/raising-a-pr.md - Manage Dependencies: development/dependency-management.md - Testing: development/testing.md + - API Reference: + - Etcd Druid API: api-reference/etcd-druid-api.md - Monitoring: - Metrics: monitoring/metrics.md - Proposals: