--- apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: annotations: controller-gen.kubebuilder.io/version: v0.19.0 name: upgradeoperations.kvm.ng.tidbcloud.com spec: group: kvm.ng.tidbcloud.com names: kind: UpgradeOperation listKind: UpgradeOperationList plural: upgradeoperations shortNames: - kuo - kuop singular: upgradeoperation scope: Namespaced versions: - additionalPrinterColumns: - jsonPath: .spec.dataPlaneId name: DataPlane type: string - jsonPath: .spec.targetVersion name: TargetVersion type: string - jsonPath: .status.phase name: Phase type: string - jsonPath: .status.currentStep.target name: CurrentStep type: string - jsonPath: .spec.schedule name: Schedule type: string - jsonPath: .metadata.creationTimestamp name: Age type: date name: v1 schema: openAPIV3Schema: description: |- UpgradeOperation is the Schema for the upgradeoperations API It orchestrates K8s version upgrades across data planes by coordinating between dataplane-manager (DPMGR) and cluster-service-ng (CSNG) components properties: apiVersion: description: |- APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string kind: description: |- Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string metadata: type: object spec: description: spec defines the desired state of UpgradeOperation properties: dataPlaneId: description: |- dataPlaneID specifies the data plane to upgrade This ID is used when calling DPMGR APIs (UpgradeDataPlane, GetK8sInformation, DeleteNodePool) minLength: 1 type: string expectedDuration: default: 2h description: |- expectedDuration is the expected total duration for the upgrade Used for monitoring and alerting purposes type: string paused: default: false description: |- paused indicates whether the upgrade operation is paused When paused, the current step will complete but no new steps will start type: boolean schedule: description: |- schedule specifies when the upgrade should start Format: RFC3339 timestamp (e.g., "2024-01-15T02:00:00Z") format: date-time type: string steps: description: |- steps defines the ordered sequence of upgrade steps to execute Typical step sequence: 1. dataplane-infra (DPMGR: control-plane, addons, admin-nodes, create worker nodepools) 2. PD (CSNG: PD, PD_TSO, PD_SCHEDULING) 3. TIFLASH (CSNG: TIFLASH_COMPUTE, TIFLASH_WRITE) 4. TIKV (CSNG: TiKV pods) 5. TIDB (CSNG: TiDB pods) 6. TIPROXY (CSNG: TiProxy pods) 7. TICDC (TiCDC-Service: TiCDC pods) 8. cleanup-nodepools (DPMGR: delete old worker nodepools) items: description: |- UpgradeStep defines a single upgrade step in the upgrade operation This structure is used in both spec and status: - In spec.steps: defines the desired upgrade plan (only spec fields are set) - In status.currentStep/completedSteps/pendingSteps: tracks execution state (both spec and status fields) properties: beginTime: description: |- beginTime records when this step started execution [STATUS FIELD] Set by controller when step execution begins format: date-time type: string componentIds: description: |- Specifies which component instances (by ID) to upgrade in this step. Applicable for component-based targets (e.g., TIKV, TIDB, TIPROXY). Empty means upgrade all components of the specified target type in the selected resource pools. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array duration: description: |- duration records how long this step took to complete [STATUS FIELD] Calculated by controller: endTime - beginTime type: string endTime: description: |- endTime records when this step completed [STATUS FIELD] Set by controller when step execution finishes format: date-time type: string firstFailureTime: description: |- firstFailureTime records when this step first failed Used for duration-based retry logic to determine if retry duration has been exceeded [STATUS FIELD] Set by controller on first failure, cleared on success format: date-time type: string lastAPICallTime: description: |- lastAPICallTime records when the last API call was made for this step This is used internally to avoid duplicate API calls on retry/reconcile [STATUS FIELD] Set by controller when calling upgrade APIs format: date-time type: string message: description: |- message provides additional information about the step execution [STATUS FIELD] Updated by controller during step execution type: string options: additionalProperties: type: string description: |- options specifies additional options for the upgrade step Common options across all targets: - "timeout": "60m" - timeout for this step, should trigger an alert if exceeded Empty means no timeout - "retry-duration": "5m" - duration-based retry on failure (e.g., "5m", "10m") Retries will continue within this duration before marking the step as failed For cleanup-nodepools: - "versions-to-delete": "1.32,1.33" - comma-separated list of K8s versions to delete (REQUIRED) Example: when upgrading from 1.32 to 1.34, specify "1.32,1.33" to delete old worker nodepools Note: DPMGR DeleteNodePool API requires k8s_version parameter [SPEC FIELD] Defined in spec.steps, copied to status during execution type: object resourcePoolIds: description: |- Specifies which resource pools (by ID) to upgrade in this step. Empty means upgrade all resource pools in the data plane. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array target: description: |- target specifies which component/service to upgrade Different targets correspond to different API calls: - dataplane-infra: calls DPMGR UpgradeDataPlane - cleanup-nodepools: calls DPMGR DeleteNodePool - Specific ComponentTypes (PD, TIKV, TIDB, TIPROXY, TICDC, etc.): calls CSNG or TiCDC-Service [SPEC FIELD] Defined in spec.steps, copied to status during execution enum: - dataplane-infra - cleanup-nodepools - TIKV - TIDB - PD - TIPROXY - TICDC - TIKV_WORKER - COPROCESSOR_WORKER - TIDB_WORKER - PD_TSO - PD_SCHEDULING - TIFLASH_WRITE - TIFLASH_COMPUTE - RESOURCE_MANAGER type: string version: description: |- version specifies the target K8s version for this step [SPEC FIELD] Defined in spec.steps, copied to status during execution pattern: ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.-]+)?$ type: string required: - target - version type: object minItems: 1 type: array targetVersion: description: targetVersion specifies the target K8s version to upgrade to (e.g., "1.33", "1.34", "v1.34.1-aliyun.1") pattern: ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.-]+)?$ type: string ttl: default: 8760h description: |- ttl is the time to live for completed/failed UpgradeOperation resources After this duration, the resource can be automatically cleaned up type: string required: - dataPlaneId - schedule - steps - targetVersion type: object status: description: status defines the observed state of UpgradeOperation properties: actualDuration: description: actualDuration records the actual time taken for the upgrade type: string beginTime: description: beginTime records when the upgrade operation started format: date-time type: string completedSteps: description: completedSteps contains all steps that have been successfully completed items: description: |- UpgradeStep defines a single upgrade step in the upgrade operation This structure is used in both spec and status: - In spec.steps: defines the desired upgrade plan (only spec fields are set) - In status.currentStep/completedSteps/pendingSteps: tracks execution state (both spec and status fields) properties: beginTime: description: |- beginTime records when this step started execution [STATUS FIELD] Set by controller when step execution begins format: date-time type: string componentIds: description: |- Specifies which component instances (by ID) to upgrade in this step. Applicable for component-based targets (e.g., TIKV, TIDB, TIPROXY). Empty means upgrade all components of the specified target type in the selected resource pools. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array duration: description: |- duration records how long this step took to complete [STATUS FIELD] Calculated by controller: endTime - beginTime type: string endTime: description: |- endTime records when this step completed [STATUS FIELD] Set by controller when step execution finishes format: date-time type: string firstFailureTime: description: |- firstFailureTime records when this step first failed Used for duration-based retry logic to determine if retry duration has been exceeded [STATUS FIELD] Set by controller on first failure, cleared on success format: date-time type: string lastAPICallTime: description: |- lastAPICallTime records when the last API call was made for this step This is used internally to avoid duplicate API calls on retry/reconcile [STATUS FIELD] Set by controller when calling upgrade APIs format: date-time type: string message: description: |- message provides additional information about the step execution [STATUS FIELD] Updated by controller during step execution type: string options: additionalProperties: type: string description: |- options specifies additional options for the upgrade step Common options across all targets: - "timeout": "60m" - timeout for this step, should trigger an alert if exceeded Empty means no timeout - "retry-duration": "5m" - duration-based retry on failure (e.g., "5m", "10m") Retries will continue within this duration before marking the step as failed For cleanup-nodepools: - "versions-to-delete": "1.32,1.33" - comma-separated list of K8s versions to delete (REQUIRED) Example: when upgrading from 1.32 to 1.34, specify "1.32,1.33" to delete old worker nodepools Note: DPMGR DeleteNodePool API requires k8s_version parameter [SPEC FIELD] Defined in spec.steps, copied to status during execution type: object resourcePoolIds: description: |- Specifies which resource pools (by ID) to upgrade in this step. Empty means upgrade all resource pools in the data plane. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array target: description: |- target specifies which component/service to upgrade Different targets correspond to different API calls: - dataplane-infra: calls DPMGR UpgradeDataPlane - cleanup-nodepools: calls DPMGR DeleteNodePool - Specific ComponentTypes (PD, TIKV, TIDB, TIPROXY, TICDC, etc.): calls CSNG or TiCDC-Service [SPEC FIELD] Defined in spec.steps, copied to status during execution enum: - dataplane-infra - cleanup-nodepools - TIKV - TIDB - PD - TIPROXY - TICDC - TIKV_WORKER - COPROCESSOR_WORKER - TIDB_WORKER - PD_TSO - PD_SCHEDULING - TIFLASH_WRITE - TIFLASH_COMPUTE - RESOURCE_MANAGER type: string version: description: |- version specifies the target K8s version for this step [SPEC FIELD] Defined in spec.steps, copied to status during execution pattern: ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.-]+)?$ type: string required: - target - version type: object type: array conditions: description: |- conditions represent the current state of the UpgradeOperation resource Known condition types: - "Completed": indicates whether the upgrade completed successfully - "Failed": indicates whether the upgrade failed items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format: date-time type: string message: description: |- message is a human readable message indicating details about the transition. This may be an empty string. maxLength: 32768 type: string observedGeneration: description: |- observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format: int64 minimum: 0 type: integer reason: description: |- reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: description: status of the condition, one of True, False, Unknown. enum: - "True" - "False" - Unknown type: string type: description: type of condition in CamelCase or in foo.example.com/CamelCase. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime - message - reason - status - type type: object type: array x-kubernetes-list-map-keys: - type x-kubernetes-list-type: map currentStep: description: currentStep is the step currently being executed properties: beginTime: description: |- beginTime records when this step started execution [STATUS FIELD] Set by controller when step execution begins format: date-time type: string componentIds: description: |- Specifies which component instances (by ID) to upgrade in this step. Applicable for component-based targets (e.g., TIKV, TIDB, TIPROXY). Empty means upgrade all components of the specified target type in the selected resource pools. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array duration: description: |- duration records how long this step took to complete [STATUS FIELD] Calculated by controller: endTime - beginTime type: string endTime: description: |- endTime records when this step completed [STATUS FIELD] Set by controller when step execution finishes format: date-time type: string firstFailureTime: description: |- firstFailureTime records when this step first failed Used for duration-based retry logic to determine if retry duration has been exceeded [STATUS FIELD] Set by controller on first failure, cleared on success format: date-time type: string lastAPICallTime: description: |- lastAPICallTime records when the last API call was made for this step This is used internally to avoid duplicate API calls on retry/reconcile [STATUS FIELD] Set by controller when calling upgrade APIs format: date-time type: string message: description: |- message provides additional information about the step execution [STATUS FIELD] Updated by controller during step execution type: string options: additionalProperties: type: string description: |- options specifies additional options for the upgrade step Common options across all targets: - "timeout": "60m" - timeout for this step, should trigger an alert if exceeded Empty means no timeout - "retry-duration": "5m" - duration-based retry on failure (e.g., "5m", "10m") Retries will continue within this duration before marking the step as failed For cleanup-nodepools: - "versions-to-delete": "1.32,1.33" - comma-separated list of K8s versions to delete (REQUIRED) Example: when upgrading from 1.32 to 1.34, specify "1.32,1.33" to delete old worker nodepools Note: DPMGR DeleteNodePool API requires k8s_version parameter [SPEC FIELD] Defined in spec.steps, copied to status during execution type: object resourcePoolIds: description: |- Specifies which resource pools (by ID) to upgrade in this step. Empty means upgrade all resource pools in the data plane. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array target: description: |- target specifies which component/service to upgrade Different targets correspond to different API calls: - dataplane-infra: calls DPMGR UpgradeDataPlane - cleanup-nodepools: calls DPMGR DeleteNodePool - Specific ComponentTypes (PD, TIKV, TIDB, TIPROXY, TICDC, etc.): calls CSNG or TiCDC-Service [SPEC FIELD] Defined in spec.steps, copied to status during execution enum: - dataplane-infra - cleanup-nodepools - TIKV - TIDB - PD - TIPROXY - TICDC - TIKV_WORKER - COPROCESSOR_WORKER - TIDB_WORKER - PD_TSO - PD_SCHEDULING - TIFLASH_WRITE - TIFLASH_COMPUTE - RESOURCE_MANAGER type: string version: description: |- version specifies the target K8s version for this step [SPEC FIELD] Defined in spec.steps, copied to status during execution pattern: ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.-]+)?$ type: string required: - target - version type: object endTime: description: endTime records when the upgrade operation completed or failed format: date-time type: string k8sInfo: description: |- k8sInfo contains the K8s information from DPMGR GetK8sInformation API This is used to track the actual upgrade progress of control plane, addons, and node pools properties: addons: description: addons contains the current versions of K8s add-ons items: description: K8sAddon represents a K8s add-on and its version properties: k8sVersion: description: k8sVersion is the target K8s cluster version type: string name: description: name is the add-on name type: string targetVersion: description: targetVersion is the target version specified for this add-on type: string version: description: |- version is the current actual version of this add-on it's different from the K8s cluster version type: string type: object type: array cloudProvider: description: CloudProvider indicates which cloud provider this K8s cluster is running on type: string controlPlane: description: controlPlane contains the control plane information properties: name: description: name is the K8s cluster name type: string version: description: version is the current actual version of the control plane type: string type: object expectedWorkerNodePoolCount: description: |- expectedWorkerNodePoolCount is the expected number of worker node pools for the target version For EKS PerZonePerInstanceType mode: nodePools × zones format: int32 type: integer nodePools: description: nodePools contains information about all node pools items: description: K8sNodePool represents a node pool and its K8s version properties: count: description: count is the number of nodes in this pool format: int32 type: integer deleting: description: deleting indicates whether this node pool is being deleted type: boolean kind: description: kind indicates whether this is an admin or worker node pool type: string name: description: name is the node pool name type: string ready: description: ready indicates whether this node pool is in ACTIVE status type: boolean version: description: version is the current actual K8s version of this node pool type: string type: object type: array targetVersion: description: targetVersion is the target version specified in AppBox type: string type: object message: description: message provides human-readable information about the current state type: string observedGeneration: description: observedGeneration reflects the generation of the most recently observed UpgradeOperation format: int64 type: integer pendingSteps: description: pendingSteps contains all steps that are waiting to be executed items: description: |- UpgradeStep defines a single upgrade step in the upgrade operation This structure is used in both spec and status: - In spec.steps: defines the desired upgrade plan (only spec fields are set) - In status.currentStep/completedSteps/pendingSteps: tracks execution state (both spec and status fields) properties: beginTime: description: |- beginTime records when this step started execution [STATUS FIELD] Set by controller when step execution begins format: date-time type: string componentIds: description: |- Specifies which component instances (by ID) to upgrade in this step. Applicable for component-based targets (e.g., TIKV, TIDB, TIPROXY). Empty means upgrade all components of the specified target type in the selected resource pools. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array duration: description: |- duration records how long this step took to complete [STATUS FIELD] Calculated by controller: endTime - beginTime type: string endTime: description: |- endTime records when this step completed [STATUS FIELD] Set by controller when step execution finishes format: date-time type: string firstFailureTime: description: |- firstFailureTime records when this step first failed Used for duration-based retry logic to determine if retry duration has been exceeded [STATUS FIELD] Set by controller on first failure, cleared on success format: date-time type: string lastAPICallTime: description: |- lastAPICallTime records when the last API call was made for this step This is used internally to avoid duplicate API calls on retry/reconcile [STATUS FIELD] Set by controller when calling upgrade APIs format: date-time type: string message: description: |- message provides additional information about the step execution [STATUS FIELD] Updated by controller during step execution type: string options: additionalProperties: type: string description: |- options specifies additional options for the upgrade step Common options across all targets: - "timeout": "60m" - timeout for this step, should trigger an alert if exceeded Empty means no timeout - "retry-duration": "5m" - duration-based retry on failure (e.g., "5m", "10m") Retries will continue within this duration before marking the step as failed For cleanup-nodepools: - "versions-to-delete": "1.32,1.33" - comma-separated list of K8s versions to delete (REQUIRED) Example: when upgrading from 1.32 to 1.34, specify "1.32,1.33" to delete old worker nodepools Note: DPMGR DeleteNodePool API requires k8s_version parameter [SPEC FIELD] Defined in spec.steps, copied to status during execution type: object resourcePoolIds: description: |- Specifies which resource pools (by ID) to upgrade in this step. Empty means upgrade all resource pools in the data plane. [SPEC FIELD] Defined in spec.steps, copied to status during execution items: type: string type: array target: description: |- target specifies which component/service to upgrade Different targets correspond to different API calls: - dataplane-infra: calls DPMGR UpgradeDataPlane - cleanup-nodepools: calls DPMGR DeleteNodePool - Specific ComponentTypes (PD, TIKV, TIDB, TIPROXY, TICDC, etc.): calls CSNG or TiCDC-Service [SPEC FIELD] Defined in spec.steps, copied to status during execution enum: - dataplane-infra - cleanup-nodepools - TIKV - TIDB - PD - TIPROXY - TICDC - TIKV_WORKER - COPROCESSOR_WORKER - TIDB_WORKER - PD_TSO - PD_SCHEDULING - TIFLASH_WRITE - TIFLASH_COMPUTE - RESOURCE_MANAGER type: string version: description: |- version specifies the target K8s version for this step [SPEC FIELD] Defined in spec.steps, copied to status during execution pattern: ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.-]+)?$ type: string required: - target - version type: object type: array phase: description: phase describes the current phase of the upgrade operation enum: - Pending - Running - Completed - Failed type: string resourcePools: description: |- resourcePools contains the status of shared resource pools This is used to track the upgrade progress of shared components items: description: ResourcePool represents a shared resource pool properties: components: description: components contains the list of components in this resource pool items: description: ResourcePoolComponent represents a component in a resource pool properties: componentType: description: componentType is the type of the component (e.g., PD, TIKV, TIDB) type: string id: description: id is the component ID type: string nodeVersion: description: nodeVersion is the current node version of the component type: string phase: description: phase is the current phase of the component type: string version: description: version is the current version of the component type: string type: object type: array id: description: id is the resource pool ID type: string phase: description: phase is the current phase of the resource pool type: string version: description: version is the current version of the resource pool type: string type: object type: array type: object required: - spec type: object served: true storage: true subresources: status: {}