Skip to main content
Version: 2.0.0-alpha.1 (preview)

Instance

An Instance is one running deployment of a technology. It is namespaced and references a cluster-scoped Provider, which reconciles it.

Example​

apiVersion: core.openeverest.io/v1alpha1
kind: Instance
metadata:
name: orders-db
namespace: demo
spec:
providerRef:
name: provider-percona-postgresql
version: 18.4-1
topology:
type: cluster
components:
engine:
replicas: 3
resources:
requests:
cpu: "1"
memory: 2Gi
limits:
cpu: "1"
memory: 2Gi
storage:
size: 50Gi
storageClass: fast-ssd
proxy:
type: pgbouncer
replicas: 2
service:
serviceType: LoadBalancer
backup:
enabled: true
classRef:
name: pg
storages:
- storageRef:
name: s3-backups
schedules:
- name: daily
enabled: true
cron: "0 2 * * *"
retention:
type: count
count: 7
pitr:
enabled: true
deletionPolicy: Cascade

Spec​

FieldDescription
providerRef.nameRequired. Name of the Provider. List them with kubectl get providers.
versionVersion bundle to deploy. Defaults to the provider's defaultVersion.
topology.typeTopology, as defined by the provider in spec.topologies. When omitted, the provider decides; set it explicitly when the provider offers more than one.
topology.parametersTopology-level settings defined by the provider.
parametersInstance-level settings defined by the provider.
componentsMap of component name to component settings. Valid names depend on the provider and topology.
backupBackup class, storages, schedules and point-in-time recovery. See Backups and restores.
dataSourceCreate the instance from a backup or a point in time. See Create an instance from a backup.
monitoring.destinationsUp to 8 monitoring destinations to send to, each with a name, a destinationRef.name and optional parameters. See Monitoring.
userSecretRef.nameSecret with the initial credentials, for providers that support it. Immutable. When omitted, the provider generates credentials.
maintenanceHow disruptive changes are approved. See Maintenance.
deletionPolicyWhat happens to the instance's Backup and Restore resources when it is deleted: Cascade (default) deletes them, Orphan keeps them.

Fields you omit get the provider's defaults.

Components​

Each entry in spec.components configures one component. The provider decides which fields each component supports — see the topology's supportedFields in the Provider.

FieldDescription
typeComponent type, when the provider offers several — for example the proxy type.
version, imageOverride the version or image of this component.
replicasNumber of pods.
resourcesCPU and memory requests and limits, as in a Kubernetes container.
storage.size, storage.storageClassSize and StorageClass of the data volumes.
service.serviceTypeHow the component is exposed: ClusterIP, NodePort or LoadBalancer. service.annotations and service.loadBalancerService configure the service further.
schedulingPolicynodeSelector, affinity, tolerations, topologySpreadConstraints and schedulerName. See Pod scheduling.
parametersComponent settings defined by the provider, such as engine configuration.

Maintenance​

Some changes need a restart or downtime — for example, the new images that a provider upgrade brings. spec.maintenance decides which of them the provider applies on its own:

FieldDescription
maintenance.autoApproveUpToThe most disruptive change applied automatically: NonDisruptive (default), RollingRestart or Downtime.
maintenance.approvedOne-time approval for a held change. Set it to the approvalToken of the change in status.pendingMaintenance.

Held changes are listed in status.pendingMaintenance with a description, a severity and an approval token. Version changes that you request through spec.version are not held.

Status​

The status follows the Kubernetes API conventions: conditions are the source of truth, and the phase is only a coarse label for display. Tools that read conditions, such as kubectl wait, Argo CD, Flux and Helm, understand the state of an instance without knowing anything about the provider.

FieldDescription
phasePending — the instance has never served clients; Provisioned — it has been available at least once; Terminating — it is being deleted. Use it for wording only, never to decide what to do.
observedGenerationThe metadata.generation of the spec the status describes. While it is lower than metadata.generation, the provider has not reported on the latest change yet. It is -1 until a provider first reports.
versionThe version bundle that is currently applied.
conditionsSee Conditions.
componentsFor each component: the label selector of its pods, replicas (the pods that are not terminating), readyReplicas, and desiredReplicas (how many pods it will have once the current spec is applied).
connectionSecretRefThe Secret with the connection details, named <instance>-conn. See Connect to an instance.
backupThe state of each backup storage, including its point-in-time recovery window. See Instance backup settings.
monitoringThe metrics endpoints the instance exposes (sources) and the state of each monitoring destination (destinations).
pendingMaintenanceDisruptive changes waiting for approval.

kubectl get instances shows the AVAILABLE and STATUS columns; -o wide adds PHASE, STALLED, TOPOLOGY and MESSAGE. spec.providerRef can't be changed after creation.

Conditions​

Summary conditions answer the questions every reader has:

ConditionQuestion
AvailableCan clients use the instance right now? It stays True through a rolling change of a highly available instance, and is False while a restore replaces the data.
ReadyHas the latest spec been carried out in full? Its reason is the status word that the UI, everestctl and kubectl get show — for example Ready, Creating, ApplyingChanges, Upgrading, Restoring, CrashLoopBackOff or BackupStorageNotFound — and its message is a sentence you can act on.
ReconcilingIs the provider still working on it? Wait.
StalledHas progress stopped in a way that waiting won't fix? Act. While Ready is not True, exactly one of Reconciling and Stalled is True.
NeedsAttentionIs there a problem someone may want to look at? It is True as soon as a check fails, before it is known whether the problem clears by itself.

Checks are True when fine, Unknown while not known yet, and False when there is a problem. These gate Ready:

CheckFalse when
ReferencesResolvedThe provider, the user Secret or another object the instance names is missing or doesn't fit.
SyncedThe provider's calls to apply the spec or read the state have failed for a minute in a row.
PodsScheduledA pod has waited more than a minute for a node. The message says which component and why.
PodsReadyA pod is in a back-off: CrashLoopBackOff, ImagePullBackOff or CreateContainerConfigError. It is Unknown with reason NotReady while pods are only starting.
EngineHealthyThe provider reports a problem with the engine.
DataSourceReadyThe instance can't be created from its spec.dataSource. Set only for instances created from a backup.
BackupConfiguredA backup storage or the backup class can't be used. Set only when backups are enabled.

These checks don't gate Ready: ConnectionDetailsReady (the connection Secret is filled in), MonitoringConfigured and MonitoringReady (see Monitoring).

Operations are True while a long operation runs, then False with reason Succeeded: Restoring, Upgrading and StorageResizing. While one runs, it gives Ready its status word.

Other conditions: MaintenancePending (a disruptive change waits for approval), ComponentVersionDeprecated (a component runs a version the provider deprecated) and Unattended.

When an instance is stalled​

SituationStalled becomes True
The provider rejects the spec (reason ValidationFailed), gives up retrying, or reports a problem it can't recover fromAt once
A check fails, for example a missing Secret, a crash loop or pods that can't be scheduledAfter 10 minutes. Until then, only NeedsAttention is True.
Nothing fails, but nothing finishes either, and no operation runsAfter 30 minutes

The deadlines start again when you change the spec.

When no provider reconciles the instance​

Only the provider named in spec.providerRef updates an instance's status. When it doesn't, OpenEverest sets the Unattended condition itself:

SituationUnattended
The provider in spec.providerRef doesn't exist, for 1 minute — for example because of a typoTrue, reason ProviderNotFound. The message lists the installed providers.
The provider exists, but hasn't reported on the current spec for 5 minutesUnknown, reason NotResponding. Check that the provider is running, and its logs.

Unattended is present only while something is wrong, and is removed as soon as the provider catches up. Because spec.providerRef can't be changed, delete an instance that names the wrong provider and create it again.

Example​

A PostgreSQL instance that is starting:

status:
phase: Pending
observedGeneration: 1
components:
- name: engine
replicas: 2
desiredReplicas: 2
readyReplicas: 0
selector: core.openeverest.io/component=engine,core.openeverest.io/instance=orders-db
- name: proxy
replicas: 2
desiredReplicas: 2
readyReplicas: 0
selector: core.openeverest.io/component=proxy,core.openeverest.io/instance=orders-db
conditions:
- type: Available
status: "False"
reason: NotAvailable
- type: Ready
status: "False"
reason: Creating
message: Waiting for the database to start
- type: Reconciling
status: "True"
reason: Creating
message: Waiting for the database to start
- type: Stalled
status: "False"
reason: Reconciling
- type: NeedsAttention
status: "False"
reason: NoProblems
- type: ReferencesResolved
status: "True"
reason: Resolved
- type: Synced
status: "True"
reason: Synced
- type: PodsScheduled
status: "True"
reason: Scheduled
- type: PodsReady
status: "Unknown"
reason: NotReady
message: |-
engine: 2 of 2 pods are not ready
proxy: 2 of 2 pods are not ready
- type: BackupConfigured
status: "True"
reason: Configured
message: Backup configuration applied to engine

To wait until an instance has applied its latest spec:

kubectl wait instance/orders-db -n demo --for=condition=Ready --timeout=10m