Project: KubeBlocks by ApeCloud (App Definition and Development / Database)
File: template.md

We're happy to announce the release of KubeBlocks $kubeblocks_version! We would like to extend our appreciation to all contributors who helped make this release happen. Breaking changes Reconstructed existing "dbaas.kubeblocks.io" API group to new "apps.kubeblocks.io" API group, affected following APIs: ClusterDefinition ClusterVersion Cluster ConfigConstraint OpsRequest Refactored ConfigTemplate related API, affected following APIs: ClusterDefinition ClusterVersion Existing APIs will no longer be functional, please make sure you have removed the deprecated APIs and transformed CRDs before upgrade. Please refer to the upgrade notes under this release notes. Highlights Automatic pod container environment variables updates: [NEW] KBPODFQDN - KubeBlocks Cluster component workload associated headless service name, N/A if workloadType=Stateless. [NEW] KBPODIP - Pod IP address [NEW] KBPODIPS - Pod IP addresses [NEW] KBHOSTIP - Host IP address [DEPRECATED] KB_PODIPS - Pod IP addresses [DEPRECATED] KB_PODIP - Pod IP address [DEPRECATED] KB_HOSTIP - Host IP address KBPODNAME - Pod Name KB_NAMESPACE - Namespace KBSANAME - Service Account Name KB_NODENAME - Node Name KBCLUSTERNAME - KubeBlocks Cluster API object name KBCOMPNAME - Running pod's KubeBlocks Cluster API object's `.spec.components.name` KBCLUSTERCOMP_NAME - Running pod's KubeBlocks Cluster API object's `<.metadata.name>-<.spec.components.name>`, same name is used for Deployment or StatefulSet workload name, and Service object name New KubeBlocks addon extensions management (an addon components are part of KubeBlocks control plane extensions). Highlights include: New addons.extensions.kubeblocks.io API that provide running cluster installable check and auto-installation settings. Following addons are provided: Prometheus and Alertmanager AlertManager Webhook Adaptor Grafana KubeBlocks CSI driver S3 CSI driver Snapshot Controller KubeBlocks private network Load Balancer ApeCloud MySQL ClusterDefinition API Community PostgreSQL ClusterDefinition API Community Redis ClusterDefinition API Cluster availability demo application named NyanCat ClusterDefinition API `spec.connectionCredential` add following built-in variables: A random UUID v4 generator `$(UUID)` A random UUID v4 generator with BASE64 encoded `$(UUID_B64)` A random UUID v4 generator in UUID string then BASE64 encoded `$(UUIDSTRB64)` A random UUID v4 generator in HEX representation `$(UUID_HEX)` Service FQDN `$(SVCFQDN)` placeholder, value pattern - $(CLUSTERNAME)-$(1STCOMPNAME).$(NAMESPACE).svc, where 1STCOMPNAME is the 1st component that provide `ClusterDefinition.spec.componentDefs[].service` attribute Service ports `$(SVCPORT<NAME>)` placeholder example usage: ```yaml kind: ClusterDefinition metadata: name: my-clusterdefinition spec: connectionCredential: username: "admin" "admin-password": "$(RANDOM_PASSWD)" endpoint: "http://$(SVCFQDN):$(SVCPORT_http)" componentsDefs: name: my-comp-type service: ports: name: http port: 8123 kind: Cluster metadata: name: my-cluster namespace: my-ns spec: clusterDefinitionRef: my-clusterdefinition componentSpecs: name: my-comp type: my-comp-type kind: Secret metadata: name: my-cluster-conn-credential namespace: my-ns labels: "app.kubernetes.io/instance": my-cluster stringData: username: "admin" admin-password: "<some random 8 characters password>" endpoint: "http://my-cluster-my-comp.my-ns.svc:8123" ``` Known issues and limitations Limitations of cluster's horizontal scale operation: Only support VolumeSnapshot API to make a clone of Cluster's PV for syncing data when horizontal scaling. Only 1st pod container and 1st volume mount associated PV will be processed for VolumeSnapshot, do assure that data volume is placed in 1st pod container's 1st volume mount. Unused PVCs will be deleted in 30 minutes after scale in. If you're new to KubeBlocks, visit the page and get a quick start with KubeBlocks. $warnings See section to upgrade KubeBlocks to version $kubeblocks_version. Thanks to everyone who made this release possible! $kubeblocks_contributors $kubeblocks_changes To upgrade to this release of KubeBlocks, follow the steps here to ensure a smooth upgrade. Release Notes for `v0.3.0`: Rename CRD name `backupjobs.dataprotection.kubeblocks.io` to `backups.dataprotection.kubeblocks.io` upgrade KubeBlocks with the following command: ``` helm upgrade --install kubeblocks kubeblocks/kubeblocks --version 0.3.0 ``` after you upgrade KubeBlocks, check CRD `backupjobs.dataprotection.kubeblocks.io` and delete it ``` kubectl delete crd backupjobs.dataprotection.kubeblocks.io ``` Rename CRD name `appversions.dbaas.kubeblocks.io` to `clusterversions.dbaas.kubeblocks.io` before you upgrade KubeBlocks, please backup your Cluster CR yaml first. ``` kubectl get cluster -oyaml > clusters.yaml ``` then replace all spec.appVersionRef to spec.clusterVersionRef in the clusters.yaml. Then, handle OpsRequest CR the same

after you upgrade KubeBlocks, you can delete the CRD `appversions.dbaas.kubeblocks.io` ``` kubectl delete crd appversions.dbaas.kubeblocks.io ``` the last step, use the above backup of Clusters and OpsRequests to apply them. ``` kubectl apply -f clusters.yaml ``` Rename group name `dbaas.kubeblocks.io` to `apps.kubeblocks.io` upgrade kubeblocks to create new CRDs, after that, you can delete the CRDs with group name`dbaas.kubeblocks.io` $kubeblocksbreakingchanges Refactored the use of labels. Existing clusters or config need to manually update their labels to ensure proper functionality. The following are specific changes: Pods of `statefulset` and `deployment` Replace label name from `app.kubernetes.io/component-name` to `apps.kubeblocks.io/component-name` Replace label name from `app.kubeblocks.io/workload-type` to `apps.kubeblocks.io/workload-type` Add label `app.kubernetes.io/version` with value `Cluster.Spec.ClusterVersionRef` Add label `app.kubernetes.io/component` with value `Cluster.Spec.ComponentSpecs.ComponentDefRef` CR `backuppolicytemplate` Replace label name from `app.kubernetes.io/created-by` to `app.kubernetes.io/managed-by` Configmap hosted by KubeBlocks and named with `*-env` suffix Replace label name from `app.kubernetes.io/config-type` to `apps.kubeblocks.io/config-type` With KubeBlocks Helm chart replaced its optional components install using sub-charts dependencies with Addons extensions API, previous version upgrade to this version will uninstall the optional components completely. recovery Automated failover and self-healing Monitoring, alerting and logs Parameter reconfigure $kubeblocks_changes `kbcli playground` supports one-command launching on running environments of Alibaba Cloud, Tencent Cloud, and GCP to experience complete KubeBlocks functionality kbcli supports creating clusters by entering CPU, memory, or class type kbcli supports tagging related resources of cluster kbcli is compatible with macOS package manager `brew` kbcli supports `preflight` command to check whether the environment meets the requirements for installing KubeBlocks kbcli adds object storage addon for storing full file backups, logs, and other data `kbcli install` runs preflight to check whether the environment meets the requirements, including node taints, storage class, and other check rules kbcli addon adds timeout parameter, printing exception information when enable fails Addon inherits the affinity and tolerations configuration of KubeBlocks `kbcli uninstall` prompts information to delete backup files, printing log information if the deletion fails ClusterDefinition API `spec.connectionCredential` add following built-in variables: Headless service FQDN `$(HEADLESSSVCFQDN)` placeholder, value pattern - `$(CLUSTERNAME)-$(1STCOMPNAME)-headless.$(NAMESPACE).svc`, where 1STCOMP_NAME is the 1st component that provide `ClusterDefinition.spec.componentDefs[].service` attribute Compatible with AWS EKS v1.22/v1.23/v1.24/v1.25 Compatible with Alibaba Cloud ACK v1.22/v1.24 Compatible with Tencent Cloud TKE standard cluster v1.22/v1.24 Compatible with GCP GKE standard cluster v1.24/v1.25 KubeBlocks limits the combination of CPU and memory to avoid unreasonable configurations that reduce resource utilization or system stability High-availability MySQL 8.0 with 4C 8GB 500GB, throughput and RT differences of various products on AWS, including ApeCloud MySQL Raft group, AWS RDS operator, Operator for Percona Server for MySQL, Oracle MySQL Operator for Kubernetes New APIs: backuppolicytemplates.apps.kubeblocks.io Deleted APIs: backuppolicytemplates.dataprotection.kubeblocks.io New API attributes: clusterdefinitions.apps.kubeblocks.io API spec.type spec.componentDefs.customLabelSpecs clusterversions.apps.kubeblocks.io API spec.componentVersions.clientImage (EXPERIMENTAL) clusters.apps.kubeblocks.io API spec.componentSpecs.classDefRef spec.componentSpecs.serviceAccountName configconstraints.apps.kubeblocks.io API spec.reloadOptions.shellTrigger.namespace spec.reloadOptions.shellTrigger.scriptConfigMapRef spec.reloadOptions.tplScriptTrigger.sync spec.selector opsrequests.apps.kubeblocks.io API spec.restoreFrom spec.verticalScaling.class status.reconfiguringStatus.configurationStatus.updatePolicy backuppolicies.dataprotection.kubeblocks.io API spec.full spec.logfile spec.retention backups.dataprotection.kubeblocks.io status.manifests backuptools.dataprotection.kubeblocks.io spec.type Renamed API attributes: clusterdefinitions.apps.kubeblocks.io API spec.componentDefs.horizontalScalePolicy.backupTemplateSelector -> spec.componentDefs.horizontalScalePolicy.backupPolicyTemplateName spec.componentDefs.probe.roleChangedProbe -> spec.componentDefs.probe.roleProbe backuppolicies.dataprotection.kubeblocks.io API spec.full restorejobs.dataprotection.kubeblocks.io API spec.target.secret.passwordKeyword -> spec.target.secret.passwordKey spec.target.secret.userKeyword -> spec.target.secret.usernameKey addons.extensions.kubeblocks.io API spec.helm.installValues.secretsRefs -> spec.helm.installValues.secretRefs Deleted API attributes: opsrequests.apps.kubeblocks.io API status.observedGeneration backuppolicies.dataprotection.kubeblocks.io API spec.backupPolicyTemplateName spec.backupToolName spec.backupType spec.backupsHistoryLimit spec.hooks spec.incremental backups.dataprotection.kubeblocks.io API spec.ttl status.CheckPoint status.checkSum addons.extensions.kubeblocks.io API spec.helm.valuesMapping.jsonMap.additionalProperties spec.helm.valuesMapping.valueMap.additionalProperties spec.helm.valuesMapping.extras.jsonMap.additionalProperties spec.helm.valuesMapping.extras.valueMap.additionalProperties Updates API Status info: clusters.apps.kubeblocks.io API status.components.phase valid values are Running, Stopped, Failed, Abnormal, Creating, Updating; REMOVED phases are SpecUpdating, Deleting, Deleted, VolumeExpanding, Reconfiguring, HorizontalScaling, VerticalScaling, VersionUpgrading, Rebooting, Stopping, Starting. status.phase valid values are Running, Stopped, Failed, Abnormal, Creating, Updating; REMOVED phases are ConditionsError, SpecUpdating, Deleting, Deleted, VolumeExpanding, Reconfiguring, HorizontalScaling, VerticalScaling, VersionUpgrading, Rebooting, Stopping, Starting. opsrequests.apps.kubeblocks.io API status.components.phase valid values are Running, Stopped, Failed, Abnormal, Creating, Updating; REMOVED phases are SpecUpdating, Deleting, Deleted, VolumeExpanding, Reconfiguring, HorizontalScaling, VerticalScaling, VersionUpgrading, Rebooting, Stopping, Starting, Exposing. status.phase added 'Creating' phase. N/A if upgrading from 0.4