InfraClusterVersion [upgrade.alauda.io/v1alpha1]

描述
InfraClusterVersion is the long-lived desired Kubernetes and OS state of one immutable cluster. CVO sets it once per platform upgrade; the cluster's provider converges it and reports status. There is one per immutable cluster, in the Global cluster's cpaas-system, named after the cluster: the API server then guarantees at most one per cluster, and a repeated create returns AlreadyExists instead of a duplicate. Each generation is one platform upgrade.
类型
object
必填
spec

规格

属性类型描述
apiVersionstring

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

kindstring

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

metadataObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

specobject

InfraClusterVersionSpec is written only by CVO.

statusobject

InfraClusterVersionStatus is written only by the provider, and describes the generation in observedGeneration.

Core fields -- observedGeneration, phase, conditions, lock, current, startedTime and completionTime -- are what CVO reads and every provider must implement. The rest are extensions for observability that CVO does not read. All are optional in the schema: CVO creates the object with an empty status.

.spec

描述
InfraClusterVersionSpec is written only by CVO.
类型
object
必填
clusterNamedesiredinfrastructureRef
属性类型描述
clusterNamestring

clusterName is the CAPI Cluster in the same namespace. It equals metadata.name.

desiredobject

desired is the target of the current platform upgrade.

infrastructureRefobject

infrastructureRef is copied from the CAPI Cluster.

.spec.desired

描述
desired is the target of the current platform upgrade.
类型
object
必填
kubernetesVersionrelease
属性类型描述
componentsarray

components are hints only; see ComponentHint.

kubernetesVersionstring

kubernetesVersion is the final target Kubernetes version of this platform upgrade, with the leading v and the suffix, for example v1.34.5-8. The provider decides the intermediate minors on the way.

preflightRefobject

preflightRef names the InfraClusterVersionPreflight this generation was gated on. CVO always sets it in automatic mode and leaves it empty in manual mode. Providers treat it as informational.

releaseobject

release is the target ACP release of this platform upgrade.

.spec.desired.components

描述
components are hints only; see ComponentHint.
类型
array

.spec.desired.components[]

描述
ComponentHint is a version hint for one component. It is only a hint: providers must not depend on its presence or value, and CVO does not promise to fill it.
类型
object
属性类型描述
namestring
versionstring

.spec.desired.preflightRef

描述
preflightRef names the InfraClusterVersionPreflight this generation was gated on. CVO always sets it in automatic mode and leaves it empty in manual mode. Providers treat it as informational.
类型
object
属性类型描述
namestring

.spec.desired.release

描述
release is the target ACP release of this platform upgrade.
类型
object
必填
version
属性类型描述
imagestring

image is the digest-pinned release payload, for audit and tracing.

versionstring

version is the target ACP release without a leading v, for example 4.3.3, as CVO and the ClusterVersionShadow write it.

.spec.infrastructureRef

描述
infrastructureRef is copied from the CAPI Cluster.
类型
object
必填
apiVersionkind
属性类型描述
apiVersionstring
kindstring

.status

描述
InfraClusterVersionStatus is written only by the provider, and describes the generation in observedGeneration. Core fields -- observedGeneration, phase, conditions, lock, current, startedTime and completionTime -- are what CVO reads and every provider must implement. The rest are extensions for observability that CVO does not read. All are optional in the schema: CVO creates the object with an empty status.
类型
object
属性类型描述
completionTimestring

completionTime is when the current generation entered Succeeded. It is cleared when a new generation starts.

componentsarray
conditionsarray
currentobject

current is what the cluster has actually reached. kubernetesVersion advances with every completed hop, intermediate minors included; releaseVersion is written only when a whole generation succeeds.

generationStartobject

generationStart is the version at the start of the current generation. The history entry appended on success copies it into from: by then current.kubernetesVersion has moved on with every hop.

The provider writes it once, when it observes a new generation and moves it to Preparing: kubernetesVersion from the KubeadmControlPlane's spec.version, releaseVersion from current, which is empty on a new object. It does not change it again within the generation -- not across hops, restarts, leader changes or provider upgrades -- and the next generation overwrites it, except a retargeted generation, one in which CVO replaced the target of an unfinished generation: that one keeps it, so it stays the start of the whole platform upgrade. On an object created while the cluster was already mid-upgrade, for example after a disaster-recovery switchover, it is what the provider observed when it took over, which may be an intermediate version. It is for audit only; providers do not decide their next step from it, except that in a retargeted generation they use it to tell this upgrade's own rollouts, those whose spec.version is at or above its kubernetesVersion, from external ones.

historyarray

history gains one entry per completed generation, oldest first. Providers keep at most 20 entries, dropping the oldest. The schema does not enforce that limit: a cap would reject the provider's write rather than let it trim.

hopsarray

hops is the path the provider plans to walk, in order. Reset when a new generation starts; empty for a no-op generation.

lockobject

LockStatus records which provider is executing the current generation.

The cluster is locked while the current generation is unfinished, Stalled included; the lock is released when it succeeds and the record stays for audit until the next generation is taken over. There is no renewal and no time-based takeover.

observedGenerationinteger

observedGeneration is the metadata.generation the provider has observed. While it lags, the effective phase is Pending.

phasestring

InfraClusterVersionPhase is the raw phase of the generation recorded in status.observedGeneration. There is no Failed or Cancelled: a generation is forward-only and can only progress or stall.

The effective phase is Pending whenever observedGeneration lags metadata.generation, whatever this field says; an empty phase also reads as Pending.

resolvedImagesarray

resolvedImages has one entry per hop and per KubeadmControlPlane or MachineDeployment, the same shape as on InfraClusterVersionPreflight.

rolloutarray
startedTimestring

startedTime is when the current generation entered Preparing.

stepsarray

steps is the progress inside the current hop. Reset on entering each hop and when a new generation starts.

.status.components

类型
array

.status.components[]

描述
ComponentStatus is informational only: neither CVO nor any component may base a decision on it.
类型
object
属性类型描述
actionstring

ComponentAction is what the provider did, or will do, for one component.

messagestring
namestring
observedVersionstring
requestedVersionstring

.status.conditions

类型
array

.status.conditions[]

描述
Condition contains details for one aspect of the current state of this API Resource.
类型
object
必填
lastTransitionTimemessagereasonstatustype
属性类型描述
lastTransitionTimestring

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.

messagestring

message is a human readable message indicating details about the transition. This may be an empty string.

observedGenerationinteger

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.

reasonstring

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.

statusstring

status of the condition, one of True, False, Unknown.

typestring

type of condition in CamelCase or in foo.example.com/CamelCase.

.status.current

描述
current is what the cluster has actually reached. kubernetesVersion advances with every completed hop, intermediate minors included; releaseVersion is written only when a whole generation succeeds.
类型
object
属性类型描述
kubernetesVersionstring
releaseVersionstring

releaseVersion is empty when no release has been recorded, for example on an InfraClusterVersion created during its first platform upgrade.

.status.generationStart

描述
generationStart is the version at the start of the current generation. The history entry appended on success copies it into from: by then current.kubernetesVersion has moved on with every hop. The provider writes it once, when it observes a new generation and moves it to Preparing: kubernetesVersion from the KubeadmControlPlane's spec.version, releaseVersion from current, which is empty on a new object. It does not change it again within the generation -- not across hops, restarts, leader changes or provider upgrades -- and the next generation overwrites it, except a retargeted generation, one in which CVO replaced the target of an unfinished generation: that one keeps it, so it stays the start of the whole platform upgrade. On an object created while the cluster was already mid-upgrade, for example after a disaster-recovery switchover, it is what the provider observed when it took over, which may be an intermediate version. It is for audit only; providers do not decide their next step from it, except that in a retargeted generation they use it to tell this upgrade's own rollouts, those whose spec.version is at or above its kubernetesVersion, from external ones.
类型
object
属性类型描述
kubernetesVersionstring
releaseVersionstring

releaseVersion is empty when no release has been recorded, for example on an InfraClusterVersion created during its first platform upgrade.

.status.history

描述
history gains one entry per completed generation, oldest first. Providers keep at most 20 entries, dropping the oldest. The schema does not enforce that limit: a cap would reject the provider's write rather than let it trim.
类型
array

.status.history[]

描述
HistoryEntry records one completed generation, that is one platform upgrade; intermediate hops are not recorded separately.
类型
object
属性类型描述
completionTimestring
fromobject

from is the version at the start of the generation, copied from status.generationStart.

holderstring
startedTimestring
toobject

to is the final version of the generation.

.status.history[].from

描述
from is the version at the start of the generation, copied from status.generationStart.
类型
object
属性类型描述
kubernetesVersionstring
releaseVersionstring

releaseVersion is empty when no release has been recorded, for example on an InfraClusterVersion created during its first platform upgrade.

.status.history[].to

描述
to is the final version of the generation.
类型
object
属性类型描述
kubernetesVersionstring
releaseVersionstring

releaseVersion is empty when no release has been recorded, for example on an InfraClusterVersion created during its first platform upgrade.

.status.hops

描述
hops is the path the provider plans to walk, in order. Reset when a new generation starts; empty for a no-op generation.
类型
array

.status.hops[]

描述
Hop is one Kubernetes version change of at most one minor that the provider performs inside a generation. An InfraClusterVersionPreflight lists hops with kubernetesVersion only.
类型
object
属性类型描述
completionTimestring
kubernetesVersionstring
phasestring

HopPhase is the progress of one hop.

startedTimestring

.status.lock

描述
LockStatus records which provider is executing the current generation. The cluster is locked while the current generation is unfinished, Stalled included; the lock is released when it succeeds and the record stays for audit until the next generation is taken over. There is no renewal and no time-based takeover.
类型
object
属性类型描述
acquiredTimestring

acquiredTime is when holder was written. Later instances of the same provider do not rewrite it.

holderstring

holder is the provider's stable name, for example cluster-api-provider-dcs, never a pod name. "manual" is reserved for manual mode.

.status.resolvedImages

描述
resolvedImages has one entry per hop and per KubeadmControlPlane or MachineDeployment, the same shape as on InfraClusterVersionPreflight.
类型
array

.status.resolvedImages[]

描述
ResolvedImage is the image one KubeadmControlPlane or MachineDeployment uses for one hop.
类型
object
属性类型描述
imagestring

image is opaque and private to the provider: a VM template name, an ECS image name, an OCI reference, and so on.

kubernetesVersionstring

kubernetesVersion is the hop the entry belongs to, intermediate or final.

machineTemplateRefobject

machineTemplateRef is the MachineTemplate used for the hop. It may be omitted for a hop not yet entered, and on a preflight it is at most the expected name: the template need not exist.

targetRefobject

targetRef is the KubeadmControlPlane or a MachineDeployment.

.status.resolvedImages[].machineTemplateRef

描述
machineTemplateRef is the MachineTemplate used for the hop. It may be omitted for a hop not yet entered, and on a preflight it is at most the expected name: the template need not exist.
类型
object
属性类型描述
kindstring
namestring

.status.resolvedImages[].targetRef

描述
targetRef is the KubeadmControlPlane or a MachineDeployment.
类型
object
属性类型描述
kindstring
namestring

.status.rollout

类型
array

.status.rollout[]

描述
RolloutStatus counts machines for one KubeadmControlPlane or MachineDeployment. There is deliberately no per-machine detail.
类型
object
属性类型描述
readyReplicasinteger
refobject

TypedLocalReference names an object in the same namespace by kind and name, for example a KubeadmControlPlane, a MachineDeployment or a MachineTemplate.

replicasinteger
updatedReplicasinteger

.status.rollout[].ref

描述
TypedLocalReference names an object in the same namespace by kind and name, for example a KubeadmControlPlane, a MachineDeployment or a MachineTemplate.
类型
object
属性类型描述
kindstring
namestring

.status.steps

描述
steps is the progress inside the current hop. Reset on entering each hop and when a new generation starts.
类型
array

.status.steps[]

描述
Step is one provider-defined step inside the current hop, for example KubeOVN, ControlPlane or Workers/<machinedeployment>.
类型
object
属性类型描述
completionTimestring
messagestring
namestring
phasestring

StepPhase is the progress of one provider-defined step inside a hop.

startedTimestring

API 端点

可用的 API 端点如下:

  • /apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions
    • DELETE: delete collection of InfraClusterVersion
    • GET: list objects of kind InfraClusterVersion
    • POST: create a new InfraClusterVersion
  • /apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions/{name}
    • DELETE: delete the specified InfraClusterVersion
    • GET: read the specified InfraClusterVersion
    • PATCH: partially update the specified InfraClusterVersion
    • PUT: replace the specified InfraClusterVersion
  • /apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions/{name}/status
    • GET: read status of the specified InfraClusterVersion
    • PATCH: partially update status of the specified InfraClusterVersion
    • PUT: replace status of the specified InfraClusterVersion

/apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions

HTTP 方法
DELETE
描述
delete collection of InfraClusterVersion
HTTP 响应
HTTP 状态码响应体
200 - OKStatus schema
401 - UnauthorizedEmpty
HTTP 方法
GET
描述
list objects of kind InfraClusterVersion
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersionList schema
401 - UnauthorizedEmpty
HTTP 方法
POST
描述
create a new InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
请求体参数
参数类型描述
bodyInfraClusterVersion schemaapplication/json formatted
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
202 - AcceptedInfraClusterVersion schema
401 - UnauthorizedEmpty

/apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions/{name}

HTTP 方法
DELETE
描述
delete the specified InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
HTTP 响应
HTTP 状态码响应体
200 - OKStatus schema
202 - AcceptedStatus schema
401 - UnauthorizedEmpty
HTTP 方法
GET
描述
read the specified InfraClusterVersion
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP 方法
PATCH
描述
partially update the specified InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP 方法
PUT
描述
replace the specified InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
请求体参数
参数类型描述
bodyInfraClusterVersion schemaapplication/json formatted
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
401 - UnauthorizedEmpty

/apis/upgrade.alauda.io/v1alpha1/namespaces/{namespace}/infraclusterversions/{name}/status

HTTP 方法
GET
描述
read status of the specified InfraClusterVersion
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP 方法
PATCH
描述
partially update status of the specified InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP 方法
PUT
描述
replace status of the specified InfraClusterVersion
查询参数
参数类型描述
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
请求体参数
参数类型描述
bodyInfraClusterVersion schemaapplication/json formatted
HTTP 响应
HTTP 状态码响应体
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
401 - UnauthorizedEmpty