> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/guides/operations/upgrades-and-releases.md). # Upgrades and releases How administrators choose software versions and roll out upgrades across e6data - clusters, products, and platform components. This section covers how administrators choose software versions and roll out upgrades across the platform: upgrading clusters, managing product versions (Metadata Service and the optional products), deploying platform components, and understanding how rollouts, rollbacks, and failures behave. ## Key concepts | Term | Meaning | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Release version | A specific, published build of a component (for example, `3.0.183`). Each version bundles the exact images and default configuration for that component. | | Cluster | A compute (query-engine) cluster you create and run in your workspace. Each cluster runs a chosen release version, set on the cluster itself. | | Product | A platform capability that runs as its own service - the Metadata Service, plus optional products. Each product has its own version, upgraded from the **Version Upgrades** tab. | | Platform Components | The shared infrastructure of your workspace (console, API server, routing, and related services). Upgraded together as a single **platform release** from the **Platform Components** section of **Version Upgrades**. | | Available version | A version published to your workspace and ready to select. The platform keeps the list in sync automatically. | | Deprecated version | A version e6data has retired. Deprecated versions are hidden from the upgrade menus. | | Rollout | Moving a running service from its current version to a newly selected one. | | Rollback | Returning to a previous version after an upgrade. Clusters and platform releases both roll back automatically if an upgrade fails. | ## The three upgrade surfaces Different parts of the platform are upgraded in different places. This is the single most important thing to know before starting. | What you're upgrading | Where you do it | Scope | | -------------------------------------------------- | ------------------------------------------------------------- | ------------------------------ | | A cluster | The cluster's **Create / Edit** form → **Version** field | Per cluster | | A product (Metadata Service and optional products) | **Settings → Version Upgrades** (product rows) | One per product, per workspace | | Platform components | **Settings → Version Upgrades → Platform Components** section | The whole workspace platform | Products and platform share one tab: **Version Upgrades** contains a **Platform Components** section at the top, then a row per product. There is no separate "Platform Upgrades" tab. ## How versions become available You don't publish versions yourself - e6data publishes them, and your workspace picks them up automatically. New versions appear in the relevant dropdown without any action on your part. If you need the latest list immediately, you can force a refresh - see [Refreshing the version list](/query-engine/guides/operations/upgrades-and-releases/version-selection-and-admin-guide.md#refreshing-the-version-list). ## What a new workspace starts with Knowing what is - and isn't - already running the first time you open a workspace explains what you'll see on each upgrade surface before you do anything. | Component | State in a new workspace | What you'll see | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Platform components (console, routing, monitoring, related services) | **Running** - set up automatically when the workspace is provisioned | The **Platform Components** section shows **Not deployed** - no platform *release* has been deployed through it yet, but the components themselves are up | | Clusters | **None** - you create them, choosing a version each time | The Clusters list is empty until you create a cluster | | Metadata Service | Running - set up automatically when the workspace is provisioned | The Metadata Service section shows Not deployed - no metadata service has been deployed through it yet, but the components themselves are up | | Optional products | **Off until enabled.** Enabling a feature creates the product automatically on the latest version | Appear only after you turn the feature on in **Feature Enablement** | | Available versions | **Synced and ready** | Version dropdowns are populated even before anything is deployed | The nuance for platform: the components that make your workspace work are provisioned at creation time and run independently of the **Platform Components** section. That section tracks platform *releases* you deploy through it - so a healthy new workspace correctly shows **Not deployed** there. Deploying a release from that section is how you move the platform onto a managed release version. See [Platform rollout](/query-engine/guides/operations/upgrades-and-releases/rollbacks-failure-modes-recovery.md#platform-rollout). ## Architecture overview The platform separates **the list of available versions** from **what you choose to run**. * **Available versions** are published centrally and kept in sync with your workspace automatically. This is why versions show up on their own. * **What runs** is your choice: you select a version on a cluster, product, or the platform, and the platform carries out the rollout, reports progress back to the UI, and - for clusters - automatically recovers if the new version fails. The mechanics are covered in [Rollbacks, failure modes, and recovery](/query-engine/guides/operations/upgrades-and-releases/rollbacks-failure-modes-recovery.md). ## In this section * [Version selection and admin guide](/query-engine/guides/operations/upgrades-and-releases/version-selection-and-admin-guide.md) - selecting versions, refreshing the list, feature enablement, and permissions. * [Product and cluster upgrades](/query-engine/guides/operations/upgrades-and-releases/product-and-cluster-upgrades.md) - step-by-step for each upgrade surface. * [Rollbacks, failure modes, and recovery](/query-engine/guides/operations/upgrades-and-releases/rollbacks-failure-modes-recovery.md) - how rollouts and rollbacks behave, and what to do when one fails. * [Status signals](/query-engine/guides/operations/upgrades-and-releases/status-signals.md) - reading upgrade status across surfaces. ## See also * [Roles and permissions](/query-engine/guides/security/identity-and-rbac/roles-and-permissions.md) - the access control that gates upgrade actions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.e6data.com/query-engine/guides/operations/upgrades-and-releases.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.