Skip to content

Commit 35a61c3

Browse files
Watson1978kenhys
Watson1978
and
kenhys
authored
blog: add "Upgrade Guide for fluent-package v6" article (#392)
Signed-off-by: Shizuo Fujita <[email protected]> Co-authored-by: Kentaro Hayashi <[email protected]>
1 parent 2ad4d6d commit 35a61c3

File tree

5 files changed

+188
-4
lines changed

5 files changed

+188
-4
lines changed

‎content/blog/20250904_upgrade-guide-for-fluent-package-v6.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Upgrade Guide for fluent-package v6
2+
3+
On August 29, 2025, we released `fluent-package` v6 as a new series of stable packages.
4+
5+
## What is Fluent Package v6 LTS?
6+
Fluent Package v6 LTS is a long-term support (LTS), stable package of Fluentd.
7+
8+
Fluent Package v5 LTS will reach end of support at the end of 2025.
9+
As its successor, Fluent Package v6 LTS will be supported until at least the end of 2027.
10+
11+
For more details, see the following article:
12+
13+
* [fluent-package v6.0.0 has been released](https://www.fluentd.org/blog/fluent-package-v6.0.0-has-been-released)
14+
15+
## Upgrade procedure to Fluent Package v6 LTS
16+
As an example, you can upgrade with the following steps:
17+
18+
1. Check manually installed plugins
19+
2. Stop the Fluentd service
20+
3. Back up registry settings (Windows only)
21+
4. Install Fluent Package v6 LTS
22+
5. Reinstall plugins
23+
6. Restart the Fluentd service
24+
25+
Below are details for each step.
26+
27+
### 1. Check manually installed plugins
28+
If your current version (before upgrade) is Fluent Package v5.0.2 or later (v5.0.3 for Windows),
29+
you can use the bundled [fluent-diagtool](https://github.com/fluent/diagtool) to list manually installed plugins.
30+
31+
Run the following command:
32+
33+
```sh
34+
$ /opt/fluent/bin/fluent-diagtool -t fluentd -o /tmp
35+
```
36+
37+
* `-t fluentd`: required
38+
* `-o /tmp`: specifies the output directory for results (you can choose any directory)
39+
40+
The tool outputs various information to standard output.
41+
The following section shows the list of manually installed plugins:
42+
43+
```
44+
(...)
45+
2025-07-17 08:13:31 +0000: [Diagtool] [INFO] [Collect] fluent-package manually installed gem information is stored in /tmp/20250717081331/output/gem_local_list.output
46+
2025-07-17 08:13:31 +0000: [Diagtool] [INFO] [Collect] fluent-package manually installed gems:
47+
2025-07-17 08:13:31 +0000: [Diagtool] [INFO] [Collect] * fluent-plugin-remote_syslog
48+
(...)
49+
```
50+
51+
In this example, the only manually installed plugin is `fluent-plugin-remote_syslog`.
52+
The list is also saved to a file:
53+
54+
55+
* `/{output_directory}/{execution_timestamp}/output/gem_local_list.output`
56+
57+
For the above case, the list was saved to `/tmp/20250717081331/output/gem_local_list.output`.
58+
59+
If you are using a version earlier than v5.0.2, the bundled `fluent-diagtool` is outdated.
60+
Please update it in advance:
61+
62+
```sh
63+
$ sudo fluent-gem install fluent-diagtool
64+
```
65+
66+
If you cannot update `fluent-diagtool`, obtain the list of plugins with:
67+
68+
```sh
69+
$ fluent-gem list fluent-plugin
70+
```
71+
72+
**Note:**
73+
On `fluent-package` v5.0.2 for Windows or earlier, `fluent-diagtool` is not available due to a known issue.
74+
Use `fluent-gem list fluent-plugin` instead.
75+
76+
### 2. Stop the Fluentd service
77+
Stop any running Fluentd service(s).
78+
If multiple Fluentd services are running, stop them in the order: forwarders first, then aggregators.
79+
80+
### 3. Back up registry settings (Windows only)
81+
On Windows, back up registry settings needed for rollback.
82+
Run the following command in PowerShell or Command Prompt as an administrator:
83+
84+
```console
85+
> reg export HKLM\System\CurrentControlSet\Services\fluentdwinsvc C:\fluent-package-5_fluentdwinsvc.reg
86+
```
87+
88+
### 4. Install Fluent Package v6 LTS
89+
90+
Install Fluent Package v6 LTS.
91+
92+
Example for RPM Package (Red Hat Linux):
93+
94+
```sh
95+
$ curl -fsSL https://fluentd.cdn.cncf.io/sh/install-redhat-fluent-package6-lts.sh | sh
96+
```
97+
98+
Please refer to the official documentation for each environment:
99+
100+
* [RPM Package (Red Hat Linux)](https://docs.fluentd.org/installation/install-fluent-package/install-by-rpm-fluent-package)
101+
* [DEB Package (Debian/Ubuntu)](https://docs.fluentd.org/installation/install-fluent-package/install-by-deb-fluent-package)
102+
* [.msi Installer (Windows)](https://docs.fluentd.org/installation/install-fluent-package/install-by-msi-fluent-package)
103+
104+
### 5. Reinstall plugins
105+
The manually installed plugins need to be reinstalled.
106+
Reinstall the plugins identified in step 1.
107+
108+
Example:
109+
110+
```sh
111+
$ sudo fluent-gem install fluent-plugin-remote_syslog
112+
```
113+
114+
### 6. Restart the Fluentd service
115+
Restart the Fluentd service(s) you stopped in step 2.
116+
If multiple services exist, start them in the order from aggregators to forwarders.
117+
118+
**Note:**
119+
Zero-Downtime Update Settings (non-Windows)
120+
121+
From the next update onward, you can perform upgrades without stopping the service using the zero-downtime update feature (not supported on Windows).
122+
123+
You can configure how Fluentd restarts after an update:
124+
125+
* auto (default): automatically performs zero-downtime restart after update
126+
* manual: requires manual zero-downtime restart, disabling automatic plugin reinstallation and restart
127+
128+
This setting can be changed anytime and does not require restarting Fluentd itself.
129+
130+
For details, see:
131+
132+
* [fluent-package v5.2.0 has been released](https://www.fluentd.org/blog/fluent-package-v5.2.0-has-been-released)
133+
134+
135+
## Rollback from Fluent Package v6 LTS to v5
136+
### 1. Stop the Fluentd service
137+
Stop running Fluentd services, in the order from forwarders to aggregators.
138+
139+
### 2. Install Fluent Package v5 LTS
140+
On Linux, simply reinstall Fluent Package v5 LTS on top of v6. No need to uninstall v6 beforehand.
141+
On Windows, uninstall Fluent Package v6 LTS first, then install v5 LTS.
142+
143+
Manually installed plugins remain on the system, so after rollback they are still available.
144+
No reinstallation is required.
145+
146+
### 3. Restore the registry (Windows only)
147+
On Windows, restore the registry with the following command (admin PowerShell or Command Prompt):
148+
149+
```console
150+
> reg import C:\fluent-package-5_fluentdwinsvc.reg
151+
```
152+
153+
This restores Windows service auto-start settings and startup command-line arguments.
154+
155+
### 4. Restart the Fluentd service
156+
Restart the stopped Fluentd services in opposite order: aggregators first, then forwarders.
157+
158+
159+
## Download
160+
161+
Please see [the download page](/download/fluent_package).
162+
163+
## Announcement
164+
165+
### End of support for td-agent v4, let's migrate to fluent-package
166+
167+
As it was already announced [Drop schedule announcement about EOL of Treasure Agent (td-agent) 4](schedule-for-td-agent-4-eol),
168+
td-agent v4 reached EOL in Dec, 2023.
169+
170+
And fluent-package v5 will reach EOL in end of 2025.
171+
172+
We strongly recommend upgrading to fluent-package v6 LTS.
173+
174+
### Follow us on X
175+
176+
We have been posting information about Fluentd in Japanese on [@fluentd_jp](https://x.com/fluentd_jp).
177+
We would appreciate it if you followed our X account.
178+
179+
TAG: Fluentd fluent-package Announcement reminder
180+
AUTHOR: clearcode

‎content/blog/tag/announcement

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,4 +149,5 @@
149149
/blog/20250514_fluentd-v1.16.9-has-been-released
150150
/blog/20250516_fluent-package-v5.0.7-has-been-released
151151
/blog/20250806_fluentd-v1.19.0-has-been-released
152-
/blog/20250829_fluent-package-v6.0.0-has-been-released
152+
/blog/20250829_fluent-package-v6.0.0-has-been-released
153+
/blog/20250904_upgrade-guide-for-fluent-package-v6

‎content/blog/tag/fluent-package

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@
1010
/blog/20241214_fluent-package-v5.2.0-has-been-released
1111
/blog/20250214_fluent-package-v5.0.6-has-been-released
1212
/blog/20250516_fluent-package-v5.0.7-has-been-released
13-
/blog/20250829_fluent-package-v6.0.0-has-been-released
13+
/blog/20250829_fluent-package-v6.0.0-has-been-released
14+
/blog/20250904_upgrade-guide-for-fluent-package-v6

‎content/blog/tag/fluentd

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,4 +158,5 @@
158158
/blog/20250514_fluentd-v1.16.9-has-been-released
159159
/blog/20250516_fluent-package-v5.0.7-has-been-released
160160
/blog/20250806_fluentd-v1.19.0-has-been-released
161-
/blog/20250829_fluent-package-v6.0.0-has-been-released
161+
/blog/20250829_fluent-package-v6.0.0-has-been-released
162+
/blog/20250904_upgrade-guide-for-fluent-package-v6

‎content/blog/tag/reminder

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
/blog/20230731_upgrade-td-agent-v4-to-v5
22
/blog/20230829_fluent-package-scheduled-lifecycle
33
/blog/20230829_schedule-for-td-agent-4-eol
4-
/blog/20240829_fluent-package-v6-scheduled-lifecycle
4+
/blog/20240829_fluent-package-v6-scheduled-lifecycle
5+
/blog/20250904_upgrade-guide-for-fluent-package-v6

0 commit comments

Comments
 (0)