InfraClusterVersion [upgrade.alauda.io/v1alpha1]

Description
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.
Type
object
Required
spec

Specification

PropertyTypeDescription
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

Description
InfraClusterVersionSpec is written only by CVO.
Type
object
Required
clusterNamedesiredinfrastructureRef
PropertyTypeDescription
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

Description
desired is the target of the current platform upgrade.
Type
object
Required
kubernetesVersionrelease
PropertyTypeDescription
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

Description
components are hints only; see ComponentHint.
Type
array

.spec.desired.components[]

Description
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.
Type
object
PropertyTypeDescription
namestring
versionstring

.spec.desired.preflightRef

Description
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.
Type
object
PropertyTypeDescription
namestring

.spec.desired.release

Description
release is the target ACP release of this platform upgrade.
Type
object
Required
version
PropertyTypeDescription
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

Description
infrastructureRef is copied from the CAPI Cluster.
Type
object
Required
apiVersionkind
PropertyTypeDescription
apiVersionstring
kindstring

.status

Description
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.
Type
object
PropertyTypeDescription
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

Type
array

.status.components[]

Description
ComponentStatus is informational only: neither CVO nor any component may base a decision on it.
Type
object
PropertyTypeDescription
actionstring

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

messagestring
namestring
observedVersionstring
requestedVersionstring

.status.conditions

Type
array

.status.conditions[]

Description
Condition contains details for one aspect of the current state of this API Resource.
Type
object
Required
lastTransitionTimemessagereasonstatustype
PropertyTypeDescription
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

Description
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.
Type
object
PropertyTypeDescription
kubernetesVersionstring
releaseVersionstring

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

.status.generationStart

Description
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.
Type
object
PropertyTypeDescription
kubernetesVersionstring
releaseVersionstring

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

.status.history

Description
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.
Type
array

.status.history[]

Description
HistoryEntry records one completed generation, that is one platform upgrade; intermediate hops are not recorded separately.
Type
object
PropertyTypeDescription
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

Description
from is the version at the start of the generation, copied from status.generationStart.
Type
object
PropertyTypeDescription
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

Description
to is the final version of the generation.
Type
object
PropertyTypeDescription
kubernetesVersionstring
releaseVersionstring

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

.status.hops

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

.status.hops[]

Description
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.
Type
object
PropertyTypeDescription
completionTimestring
kubernetesVersionstring
phasestring

HopPhase is the progress of one hop.

startedTimestring

.status.lock

Description
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.
Type
object
PropertyTypeDescription
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

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

.status.resolvedImages[]

Description
ResolvedImage is the image one KubeadmControlPlane or MachineDeployment uses for one hop.
Type
object
PropertyTypeDescription
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

Description
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.
Type
object
PropertyTypeDescription
kindstring
namestring

.status.resolvedImages[].targetRef

Description
targetRef is the KubeadmControlPlane or a MachineDeployment.
Type
object
PropertyTypeDescription
kindstring
namestring

.status.rollout

Type
array

.status.rollout[]

Description
RolloutStatus counts machines for one KubeadmControlPlane or MachineDeployment. There is deliberately no per-machine detail.
Type
object
PropertyTypeDescription
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

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

.status.steps

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

.status.steps[]

Description
Step is one provider-defined step inside the current hop, for example KubeOVN, ControlPlane or Workers/<machinedeployment>.
Type
object
PropertyTypeDescription
completionTimestring
messagestring
namestring
phasestring

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

startedTimestring

API Endpoints

The following API endpoints are available:

  • /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 method
DELETE
Description
delete collection of InfraClusterVersion
HTTP responses
HTTP codeResponse body
200 - OKStatus schema
401 - UnauthorizedEmpty
HTTP method
GET
Description
list objects of kind InfraClusterVersion
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersionList schema
401 - UnauthorizedEmpty
HTTP method
POST
Description
create a new InfraClusterVersion
Query parameters
ParameterTypeDescription
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.
Body parameters
ParameterTypeDescription
bodyInfraClusterVersion schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
202 - AcceptedInfraClusterVersion schema
401 - UnauthorizedEmpty

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

HTTP method
DELETE
Description
delete the specified InfraClusterVersion
Query parameters
ParameterTypeDescription
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 responses
HTTP codeResponse body
200 - OKStatus schema
202 - AcceptedStatus schema
401 - UnauthorizedEmpty
HTTP method
GET
Description
read the specified InfraClusterVersion
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP method
PATCH
Description
partially update the specified InfraClusterVersion
Query parameters
ParameterTypeDescription
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 responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP method
PUT
Description
replace the specified InfraClusterVersion
Query parameters
ParameterTypeDescription
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.
Body parameters
ParameterTypeDescription
bodyInfraClusterVersion schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
401 - UnauthorizedEmpty

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

HTTP method
GET
Description
read status of the specified InfraClusterVersion
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP method
PATCH
Description
partially update status of the specified InfraClusterVersion
Query parameters
ParameterTypeDescription
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 responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
401 - UnauthorizedEmpty
HTTP method
PUT
Description
replace status of the specified InfraClusterVersion
Query parameters
ParameterTypeDescription
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.
Body parameters
ParameterTypeDescription
bodyInfraClusterVersion schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKInfraClusterVersion schema
201 - CreatedInfraClusterVersion schema
401 - UnauthorizedEmpty