diff --git a/content/influxdb3/core/admin/upgrade.md b/content/influxdb3/core/admin/upgrade.md new file mode 100644 index 000000000..818391d02 --- /dev/null +++ b/content/influxdb3/core/admin/upgrade.md @@ -0,0 +1,19 @@ +--- +title: Upgrade InfluxDB +description: > + Learn how to upgrade your {{% product-name %}} instance. +menu: + influxdb3_core: + name: Upgrade InfluxDB + parent: Administer InfluxDB +weight: 205 +influxdb3/core/tags: [upgrade, administration, catalog] +related: + - /influxdb3/core/admin/backup-restore/ + - /influxdb3/core/install/ + - /influxdb3/core/reference/config-options/ + - /influxdb3/core/admin/databases/ +source: /shared/influxdb3-admin/upgrade.md +--- + + diff --git a/content/influxdb3/core/install.md b/content/influxdb3/core/install.md index d5f092485..b9f1ec198 100644 --- a/content/influxdb3/core/install.md +++ b/content/influxdb3/core/install.md @@ -1,5 +1,5 @@ --- -title: Install {{< product-name >}} +title: Install InfluxDB 3 Core description: Download and install {{< product-name >}}. menu: influxdb3_core: @@ -9,6 +9,8 @@ influxdb3/core/tags: [install] source: /shared/influxdb3/install.md alt_links: v1: /influxdb/v1/introduction/install/ +related: + - /influxdb3/core/admin/upgrade/ --- diff --git a/content/influxdb3/enterprise/admin/upgrade.md b/content/influxdb3/enterprise/admin/upgrade.md new file mode 100644 index 000000000..b3f07ff06 --- /dev/null +++ b/content/influxdb3/enterprise/admin/upgrade.md @@ -0,0 +1,21 @@ +--- +title: Upgrade InfluxDB +description: > + Learn how to upgrade your {{% product-name %}} cluster across multiple versions, including + rolling upgrades, catalog version constraints, and recommended upgrade order + for different node modes. +menu: + influxdb3_enterprise: + name: Upgrade InfluxDB + parent: Administer InfluxDB +weight: 205 +influxdb3/enterprise/tags: [upgrade, administration, catalog] +related: + - /influxdb3/enterprise/admin/backup-restore/ + - /influxdb3/enterprise/install/ + - /influxdb3/enterprise/reference/config-options/ + - /influxdb3/enterprise/admin/databases/ +source: /shared/influxdb3-admin/upgrade.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/get-started/multi-server.md b/content/influxdb3/enterprise/get-started/multi-server.md index edeb42910..69e237a8f 100644 --- a/content/influxdb3/enterprise/get-started/multi-server.md +++ b/content/influxdb3/enterprise/get-started/multi-server.md @@ -11,6 +11,8 @@ menu: identifier: gs-multi-node-cluster weight: 102 influxdb3/enterprise/tags: [cluster, multi-node, multi-server] +related: + - /influxdb3/enterprise/admin/upgrade/ --- Create a multi-node {{% product-name %}} cluster for high availability, performance, and workload isolation. diff --git a/content/influxdb3/enterprise/install/_index.md b/content/influxdb3/enterprise/install/_index.md index ecf3f1d73..4b638f948 100644 --- a/content/influxdb3/enterprise/install/_index.md +++ b/content/influxdb3/enterprise/install/_index.md @@ -1,11 +1,13 @@ --- -title: Install {{< product-name >}} +title: Install InfluxDB 3 Enterprise description: Download and install {{< product-name >}}. menu: influxdb3_enterprise: name: Install InfluxDB 3 Enterprise weight: 2 influxdb3/enterprise/tags: [install] +related: + - /influxdb3/enterprise/admin/upgrade/ source: /shared/influxdb3/install.md alt_links: v1: /influxdb/v1/introduction/install/ diff --git a/content/influxdb3/enterprise/reference/internals/_index.md b/content/influxdb3/enterprise/reference/internals/_index.md index ed98f0368..50949aabb 100644 --- a/content/influxdb3/enterprise/reference/internals/_index.md +++ b/content/influxdb3/enterprise/reference/internals/_index.md @@ -12,5 +12,5 @@ source: /shared/influxdb3-internals-reference/_index.md + +``` +influxdb3 {{% latest-patch %}} +``` + +> [!Tip] +> ### Verify your InfluxDB version +> +> Before and after upgrading, verify the {{% product-name %}} version running on your instance. + +## Upgrade an InfluxDB 3 instance + +{{< tabs-wrapper >}} +{{% tabs %}} +[Install script](#) +[systemctl](#) +[Docker](#) +[Docker Compose](#) +[Windows](#) +{{% /tabs %}} +{{% tab-content %}} +```bash +curl -O https://www.influxdata.com/d/install_influxdb3.sh \ +&& sh install_influxdb3.sh {{< product-key >}} +``` +{{% /tab-content %}} +{{% tab-content %}} +```bash +# 1. Download the new version +curl -L https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}_linux_amd64.tar.gz \ + -o influxdb3-{{< product-key >}}.tar.gz + +# 2. Extract the archive +tar xvzf influxdb3-{{< product-key >}}.tar.gz + +# 3. Stop the service +sudo systemctl stop influxdb3 + +# 4. Install the new binary +sudo cp influxdb3 /usr/local/bin/ + +# 5. Start the service +sudo systemctl start influxdb3 +``` +{{% /tab-content %}} +{{% tab-content %}} +```bash { placeholders="CONTAINER_NAME" } +docker stop CONTAINER_NAME +docker pull influxdb:{{< product-key >}} +docker start CONTAINER_NAME +``` + +Replace the following: + +- {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}}: The name of your {{% product-name %}} container + +{{% /tab-content %}} +{{% tab-content %}} +```bash +docker compose down +docker compose pull +docker compose up -d +``` +{{% /tab-content %}} +{{% tab-content %}} +```powershell +# Download the latest Windows binary +Invoke-WebRequest ` + -Uri "https://dl.influxdata.com/influxdb/releases/influxdb3-{{< product-key >}}-{{< latest-patch >}}-windows_amd64.zip" ` + -OutFile "influxdb3-{{< product-key >}}.zip" + +# Extract the binary +Expand-Archive -Path influxdb3-{{< product-key >}}.zip -DestinationPath . -Force + +# Stop the service, replace the binary, and start the service +Stop-Service influxdb3 +Copy-Item -Path "influxdb3.exe" -Destination "C:\Program Files\InfluxData\influxdb3\" -Force +Start-Service influxdb3 +``` +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +{{% show-in "enterprise" %}} + +## Upgrade a multi-node cluster + +Upgrade {{% product-name %}} instances to newer versions using rolling upgrades to minimize downtime. +When upgrading multi-node clusters, you need to understand catalog version constraints and the recommended upgrade order for different node modes. + +- [Upgrade a single {{% product-name %}} instance](#upgrade-a-single--product-name--instance) +- [Upgrade a multi-node cluster](#upgrade-a-multi-node-cluster) + - [Before you upgrade](#before-you-upgrade) + - [Multi-node upgrade procedure](#multi-node-upgrade-procedure) + - [Upgrade constraints](#upgrade-constraints) + - [Troubleshooting](#troubleshooting) + +### Catalog version compatibility + +{{% product-name %}} uses a catalog to track metadata about tables, tags, and fields. +Some versions introduce catalog version updates that affect how nodes can interoperate during rolling upgrades. + +> [!Important] +> #### Important version transitions +> +> - **3.4.x**: Introduced a catalog version update that requires all nodes to upgrade before catalog modifications can resume. +> - **3.2.x to 3.5.x**: Nodes running 3.2.1 can temporarily coexist with nodes running 3.5.0, but catalog modifications are blocked until all nodes complete the upgrade. + +During a rolling upgrade across a catalog version boundary, nodes running older versions cannot modify the catalog. +This affects writes that add new tables, tags, or fields, but allows writes to existing tables, tags, and fields. + + + +### Multi-node upgrade procedure + +Follow these steps to upgrade your {{% product-name %}} deployment with minimal downtime. + +#### Recommended node upgrade order + +The order in which you upgrade nodes affects the availability of catalog modifications during the upgrade. +Different node modes have different impacts on catalog updates: + +- **Ingest nodes**: Primarily update the catalog when accepting writes that add new tables, tags, or fields via line protocol. +- **Query nodes**: Can accept API requests that update the catalog (for example, `influxdb3 create table`), but less frequently than ingest nodes. +- **Compactor nodes**: Rarely modify the catalog during normal operation. +- **Process nodes**: Process data without modifying the catalog structure. + +**Recommended upgrade order:** + +1. **Ingest nodes**: Upgrade ingest nodes first to restore catalog modification capability as quickly as possible. + If you have multiple ingest nodes and can route traffic while one is down, upgrade them sequentially. +2. **Query nodes**: Upgrade query nodes after upgrading all ingest nodes. +3. **Compactor nodes**: Upgrade compactor nodes last, as they have minimal impact on catalog modifications. +4. **Process nodes**: Can be upgraded at any time, as they don't modify the catalog. + +#### Perform a rolling upgrade + +Follow these steps to upgrade each node in your deployment: + +{{< tabs-wrapper >}} +{{% tabs %}} +[systemctl](#) +[Docker](#) +[Docker Compose](#) +{{% /tabs %}} +{{% tab-content %}} + +```bash +# 1. Stop the service +sudo systemctl stop influxdb3 + +# 2. Install the new version +# Follow the installation instructions for your platform: +# https://docs.influxdata.com/influxdb3/enterprise/install/ + +# 3. Start the service +sudo systemctl start influxdb3 + +# 4. Verify the version +influxdb3 --version + +# 5. Check the node's health +influxdb3 query \ + --database _internal \ + --token ADMIN_TOKEN \ + "SELECT * FROM system.queries LIMIT 5" +``` + +Replace the following: + +- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: An admin token + +{{% /tab-content %}} +{{% tab-content %}} + +```bash { placeholders="CONTAINER_NAME|NODE_ID|CLUSTER_ID|OBJECT_STORE_TYPE|ADMIN_TOKEN" } +# 1. Stop the container +docker stop CONTAINER_NAME + +# 2. Pull the latest image +docker pull influxdb:enterprise + +# 3. Start the container with the new image +# IMPORTANT: Adjust the docker run command to match your existing +# container configuration, including environment variables, volume mounts, +# object store settings, and network settings. +docker run -d \ + --name CONTAINER_NAME \ + -p 8181:8181 \ + -e INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com \ + -v ~/.influxdb3/data:/var/lib/influxdb3/data \ + influxdb:enterprise \ + influxdb3 serve \ + --node-id NODE_ID \ + --cluster-id CLUSTER_ID \ + --object-store OBJECT_STORE_TYPE \ + --data-dir /var/lib/influxdb3/data + +# 4. Verify the version +docker exec CONTAINER_NAME influxdb3 --version + +# 5. Check the node's health +docker exec CONTAINER_NAME influxdb3 query \ + --database _internal \ + --token ADMIN_TOKEN \ + "SELECT * FROM system.queries LIMIT 5" +``` + +Replace the following: + +- {{% code-placeholder-key %}}`CONTAINER_NAME`{{% /code-placeholder-key %}}: The name of your {{% product-name %}} container +- {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}: The node identifier for this instance +- {{% code-placeholder-key %}}`CLUSTER_ID`{{% /code-placeholder-key %}}: The cluster identifier for your deployment +- {{% code-placeholder-key %}}`OBJECT_STORE_TYPE`{{% /code-placeholder-key %}}: The object store type (for example, `file`, `s3`, `azure`, or `google`) +- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: An admin token + +> [!Note] +> #### Use the influxdb:enterprise image tag +> +> The `influxdb:enterprise` tag always points to the latest InfluxDB 3 Enterprise release. +> Use `docker pull influxdb:enterprise` to pull the latest version, or specify a version tag directly (for example, `influxdb:{{< latest-patch >}}-enterprise`) to upgrade to a specific version. + +> [!Important] +> If you use a cloud object store (S3, Azure, or Google Cloud), include the appropriate credentials and bucket configuration in the `docker run` command. + +{{% /tab-content %}} +{{% tab-content %}} + +```bash { placeholders="ADMIN_TOKEN" } +# 1. Stop the services +docker compose down + +# 2. Update the image in your compose.yaml file +# Change the image version to: influxdb:enterprise + +# 3. Start the services with the new image +docker compose up -d + +# 4. Verify the version +docker compose exec influxdb3 influxdb3 --version + +# 5. Check the node's health +docker compose exec influxdb3 influxdb3 query \ + --database _internal \ + --token ADMIN_TOKEN \ + "SELECT * FROM system.queries LIMIT 5" +``` + +Replace the following: + +- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: An admin token + +> [!Note] +> #### Use the influxdb:enterprise image tag +> +> The `influxdb:enterprise` tag always points to the latest InfluxDB 3 Enterprise release. +> Update the `image:` field in your `compose.yaml` to `influxdb:enterprise` to pull the latest version, or specify a version tag directly (for example, `influxdb:{{< latest-patch >}}-enterprise`) to upgrade to a specific version. +{{% /tab-content %}} +{{< /tabs-wrapper >}} + +**Repeat these steps** for each remaining node in the recommended order. + +### Rolling upgrade constraints + +Understand the constraints that apply during rolling upgrades to avoid unexpected write failures. + +#### Writes during catalog version transitions + +When upgrading from v3.3.x (or earlier) to v3.4.x, nodes running older versions cannot modify the catalog during the rolling upgrade. + +**Behavior by write type:** + +- **Writes to existing measurements, tags, and fields**: Succeed on all nodes, regardless of version. +- **Writes that add new measurements, tags, or fields**: Fail on nodes running older versions until those nodes are upgraded. + +For example, if you're upgrading from 3.2.1 to 3.5.0: + +- An ingest node running 3.2.1 can write data to existing measurements. +- An ingest node running 3.2.1 cannot write data that adds new measurements, tags, or fields. +- After upgrading the ingest node to 3.5.0, it can write data that adds new measurements, tags, or fields. + +When a node running an older version receives a write that attempts to add a new +measurement, the write fails with an error similar to: + + + +``` +Error: Catalog modification failed: node is running an older version +``` + +### Troubleshooting cluster upgrades + +#### Writes fail during upgrade + +If writes fail during a rolling upgrade, verify that you're not attempting to add new measurements, tags, or fields to nodes running older versions. + +1. **Check the write payload** to determine if it adds new measurements, tags, or fields +2. **Verify the node version** that received the write +3. **Route writes to upgraded nodes** or wait until all nodes complete the upgrade before adding new measurements, tags, or fields + +#### Upgrade order issues + +If you upgrade nodes out of the [recommended order](#recommended-node-upgrade-order), you may experience longer periods where catalog modifications are blocked. + +#### Version compatibility problems + +If nodes fail to communicate after an upgrade, verify that all nodes are running compatible versions. + +1. **Connect to each node** and [verify the version](#verify-your-current-version) +2. Review the [release notes](/influxdb3/enterprise/reference/release-notes/) for your target version to identify any breaking changes or compatibility requirements. + +#### Catalog version constraints + +Different version transitions may have different catalog version constraints. +The v3.3.x → v3.4.x transition has specific constraints, but other version transitions may differ. + +**Before upgrading**, review the [release notes](/influxdb3/enterprise/reference/release-notes/) for your target version to understand: + +- Whether the upgrade crosses a catalog version boundary +- How long catalog modifications may be blocked during the upgrade +- Any special upgrade procedures or constraints + +{{% /show-in %}} \ No newline at end of file diff --git a/content/shared/influxdb3/install.md b/content/shared/influxdb3/install.md index 6523e8a47..55f63e35e 100644 --- a/content/shared/influxdb3/install.md +++ b/content/shared/influxdb3/install.md @@ -8,8 +8,12 @@ {{% show-in "enterprise" %}} > [!Note] +> #### Multi-node cluster setup > For information about setting up a multi-node {{% product-name %}} cluster, > see [Create a multi-node cluster](/influxdb3/enterprise/get-started/multi-server/) in the Get started guide. +> +> For steps to upgrade an existing InfluxDB 3 Enterprise cluster, +> see [Upgrade InfluxDB](/influxdb3/enterprise/admin/upgrade/). {{% /show-in %}} ## System Requirements