Skip to content

Commit d4a8abd

Browse files
jstirnamanjstirnaman
committed
fix(v2): Broken link for 2.0 beta migration
Closes #5483 - Restore, update, and revise the v2-beta-to-v2 migration guide. - Skips all influx tests.
1 parent efc7e41 commit d4a8abd

File tree

1 file changed

+346
-0
lines changed

1 file changed

+346
-0
lines changed

‎content/influxdb/v2/install/upgrade/v2-beta-to-v2.md

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
---
2+
title: Upgrade from InfluxDB 2.0 beta to InfluxDB 2.0
3+
description: >
4+
To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.x, first
5+
follow these steps to upgrade your InfluxDB beta instance, data, and resources
6+
to InfluxDB 2.0.
7+
menu:
8+
influxdb_v2:
9+
parent: Upgrade InfluxDB
10+
name: InfluxDB 2.0 beta to 2.0
11+
aliases:
12+
- /influxdb/v2.0/reference/rc0-upgrade-guide/
13+
- /influxdb/v2.0/reference/rc1-upgrade-guide/
14+
- /influxdb/v2.0/reference/upgrading/rc-upgrade-guide/
15+
- /influxdb/v2.0/upgrade/v2-beta-to-v2/
16+
weight: 11
17+
related:
18+
- /influxdb/v2/install/upgrade/v2-to-v2/
19+
---
20+
21+
To upgrade from InfluxDB 2.0 beta 16 or earlier to InfluxDB 2.x, first
22+
follow these steps to upgrade your InfluxDB beta instance, data, and resources to
23+
[InfluxDB 2.0](https://github.com/influxdata/influxdb/releases/tag/v2.0.9).
24+
25+
Depending on how you have set up your InfluxDB beta instance and the importance
26+
of your existing resources and data, you can determine which steps apply to
27+
you--for example, if you don't want to migrate your data and resources,
28+
then you can skip those sections.
29+
30+
1. [Disable existing integrations](#1-disable-existing-integrations)
31+
2. [Stop existing InfluxDB beta instance](#2-stop-existing-influxdb-beta-instance)
32+
3. [(Optional) Rename existing InfluxDB binaries](#3-optional-rename-existing-influxdb-binaries)
33+
4. [Move existing data and start the latest InfluxDB](#4-move-existing-data-and-start-the-latest-influxdb)
34+
5. [Start old InfluxDB beta instance](#5-start-old-influxdb-beta-instance)
35+
6. [Create configuration profiles for the InfluxDB CLI](#6-create-configuration-profiles-for-the-influxdb-cli)
36+
7. [Copy all resources from old instance to the new one](#7-copy-all-resources-from-old-instance-to-the-new-one)
37+
8. [Set up integrations to point to new instance](#8-set-up-integrations-to-point-to-new-instance)
38+
9. [Load historical data into new instance](#9-load-historical-data-into-new-instance)
39+
40+
### Why is this manual process required?
41+
42+
To ensure that existing InfluxQL integrations work with the latest release,
43+
we had to make breaking changes to the underlying storage engine for InfluxDB 2.0.
44+
45+
{{% note %}}
46+
If you have questions while upgrading,
47+
[open an issue](https://github.com/influxdata/influxdb/issues)
48+
or join the [Community Slack workspace](https://influxcommunity.slack.com/) to
49+
get immediate help.
50+
{{% /note %}}
51+
52+
## 1. Disable existing integrations
53+
54+
To begin, shut off all integrations that are reading from, writing to, or monitoring your InfluxDB instance.
55+
This includes Telegraf, client libraries, and any custom applications.
56+
57+
## 2. Stop existing InfluxDB beta instance
58+
59+
Next, shut down your existing InfluxDB beta instance.
60+
You can manually stop the individual process using **Control+c**
61+
(or by finding the process ID with `ps aux | grep -i influxd` and using `sudo kill -9 <PID>`).
62+
If you've set `influxd` to run as a system process, follow the same steps you would use to disable any system process.
63+
64+
## 3. (Optional) Rename existing InfluxDB binaries
65+
66+
To easily identify your existing InfluxDB binaries, rename them `influx_old` and `influxd_old`.
67+
This is helpful if you've installed the binaries in your `$PATH`.
68+
We use the names `influxd_old` for this guide, but you can use whatever you like.
69+
70+
## 4. Move existing data and start the latest InfluxDB
71+
72+
If you haven't already,
73+
[download and install InfluxDB 2.0](https://github.com/influxdata/influxdb/releases/tag/v2.0.9)
74+
for your system, but don't run the setup process yet.
75+
Be careful not to overwrite the existing binaries.
76+
77+
To move data between the two instances, first configure both the old and new instances of InfluxDB to run at the same time.
78+
If you download the latest InfluxDB beta and try to start it with existing data,
79+
most likely it won't start and the following error message appears:
80+
81+
```
82+
Incompatible InfluxDB 2.0 version found.
83+
Move all files outside of engine_path before influxd will start.
84+
```
85+
86+
To avoid this error, run the following command to move your existing data to a another location (anywhere you like):
87+
88+
<!--pytest.mark.skip-->
89+
90+
```sh
91+
mv ~/.influxdbv2 ~/.influxdbv2_old
92+
```
93+
94+
Start the latest InfluxDB version by running:
95+
96+
<!--pytest.mark.skip-->
97+
98+
```sh
99+
influxd
100+
```
101+
102+
{{% note %}}
103+
If you were using specific [command line flags](/influxdb/v2/reference/cli/influxd/#flags) for InfluxDB beta, you can use those same command line flags.
104+
{{% /note %}}
105+
106+
Because the data folder path has changed for InfluxDB v2, everything will be empty.
107+
You can visit http://localhost:8086 in your browser and see a setup page, but don't go through the setup process yet.
108+
109+
## 5. Start old InfluxDB beta instance
110+
111+
You can now start your old InfluxDB instance and point it to your old data directory:
112+
113+
<!--pytest.mark.skip-->
114+
115+
```sh
116+
./influxd_old \
117+
--bolt-path ~/.influxdbv2_old/influxd.bolt \
118+
--engine-path ~/.influxdbv2_old/engine
119+
```
120+
121+
Double-check that InfluxDB is working by visiting your InfluxDB beta instance URL (probably http://localhost:9999) and logging in.
122+
Your data and resources should still be there.
123+
124+
{{% note %}}
125+
If you see a "missing migration" error, manually edit your bolt file to remove
126+
the migration--for example:
127+
128+
1. _Recommended_: **Backup your old `influxd.bolt` file**--manually editing this
129+
file could cause you to lose all your data.
130+
2. Use [BoltBrowser](https://github.com/br0xen/boltbrowser) to open and edit
131+
your old `influxd.bolt` file
132+
3. To remove the migration, highlight the record under the `migrationsv1` path
133+
and press **D**.
134+
{{% /note %}}
135+
136+
Now, the new instance and old instance of InfluxDB are running simultaneously.
137+
138+
## 6. Create configuration profiles for the InfluxDB CLI
139+
140+
Next, set up your InfluxDB CLI to connect to your old and new instances.
141+
142+
### a. Configure old profile
143+
144+
If you've used the CLI before, copy your existing `configs` file to your new data directory:
145+
146+
<!--pytest.mark.skip-->
147+
148+
```sh
149+
cp ~/.influxdbv2_old/configs ~/.influxdbv2/configs
150+
```
151+
152+
_Recommended_: rename the old configuration file to something like `influx_old`.
153+
154+
{{< keep-url >}}
155+
```toml
156+
[influx_old]
157+
url = "http://localhost:9999"
158+
token = "<YOUR TOKEN>"
159+
org = "influxdata"
160+
active = true
161+
```
162+
163+
If you've never used the CLI before, create a new configuration profile to
164+
connect to your old instance using the `influx config` command.
165+
166+
<!--pytest.mark.skip-->
167+
168+
{{< keep-url >}}
169+
```sh
170+
influx config create \
171+
--config-name influx_old \
172+
--host-url http://localhost:9999 \
173+
--org influxdata \
174+
--token <OLD_TOKEN>
175+
```
176+
177+
To list configurations, enter the following command:
178+
179+
<!--pytest.mark.skip-->
180+
181+
{{< keep-url >}}
182+
```sh
183+
influx config ls
184+
```
185+
186+
The output lists the configuration profile for your old instance:
187+
188+
```
189+
Active Name URL Org
190+
* influx_old http://localhost:9999 InfluxData
191+
```
192+
193+
### b. Configure new profile
194+
195+
Next set up your new instance, which automatically creates a configuration profile for you.
196+
197+
The `influx setup` command automatically creates a config profile named `default`.
198+
Make sure you don't already have a profile with that name before you run the command.
199+
200+
Run the `influx setup` command and answer the prompts.
201+
202+
**Don't use the same bucket name** as a bucket in your existing instance.
203+
Otherwise, a name collision and file conflict occurs when you try to copy your
204+
resources.
205+
You'll delete this dummy bucket later, after you migrate your resources.
206+
207+
<!--pytest.mark.skip-->
208+
209+
```sh
210+
influx setup
211+
```
212+
213+
The command prompts you to configure credentials:
214+
215+
```
216+
Welcome to InfluxDB 2.0!
217+
Please type your primary username: admin
218+
219+
Please type your password:
220+
221+
Please type your password again:
222+
223+
Please type your primary organization name: InfluxData
224+
225+
Please type your primary bucket name: dummy_bucket
226+
227+
Please type your retention period in hours.
228+
Or press ENTER for infinite.:
229+
230+
You have entered:
231+
Username: admin
232+
Organization: InfluxData
233+
Bucket: dummy_bucket
234+
Retention Period: infinite
235+
Confirm? (y/n): y
236+
237+
Config default has been stored in /Users/rsavage/.influxdbv2/configs.
238+
User Organization Bucket
239+
admin InfluxData dummy_bucket
240+
```
241+
242+
You now have two config profiles:
243+
one named `default` that points to your new instance, and one named `influx_old` that points to your old instance.
244+
245+
<!--pytest.mark.skip-->
246+
247+
{{< keep-url >}}
248+
```sh
249+
$ influx config ls
250+
Active Name URL Org
251+
default http://localhost:8086 InfluxData
252+
* influx_old http://localhost:9999 InfluxData
253+
```
254+
255+
You can now send commands to each of them as needed using the [`-c, --active-config`](/influxdb/v2/reference/cli/influx/#commands) option in the CLI.
256+
257+
## 7. Copy all resources from old instance to the new one
258+
259+
Use config profiles to export all resources from the old instance and apply them to your new instance.
260+
(The only things that will not be copied over are [scraper configurations](/influxdb/v2/write-data/no-code/scrape-data/manage-scrapers/).
261+
You will need to manually reconfigure those.)
262+
263+
Copy all your existing InfluxDB resources, such as dashboards, tasks, and alerts, to your new instance by running the following command:
264+
265+
<!--pytest.mark.skip-->
266+
267+
```sh
268+
influx export all -c influx_old | influx apply -c default
269+
```
270+
271+
(To learn more about this command, see
272+
[`influx export`](/influxdb/v2/reference/cli/influx/export/) and
273+
[`influx apply`](/influxdb/v2/reference/cli/influx/apply/).)
274+
275+
The output is a list of the resources created in your new instance.
276+
If successful, you can delete the bucket created during the setup.
277+
278+
<!--pytest.mark.skip-->
279+
280+
```sh
281+
LABELS +add | -remove | unchanged
282+
+-----+------------------------+----+---------------+---------+-------------+
283+
| +/- | METADATA NAME | ID | RESOURCE NAME | COLOR | DESCRIPTION |
284+
+-----+------------------------+----+---------------+---------+-------------+
285+
| + | tasty-northcutt-c9c001 | | something | #326BBA | |
286+
+-----+------------------------+----+---------------+---------+-------------+
287+
| TOTAL | 1 |
288+
+-----+------------------------+----+---------------+---------+-------------+
289+
​
290+
BUCKETS +add | -remove | unchanged
291+
+-----+------------------------+----+---------------+------------------+-------------+
292+
| +/- | METADATA NAME | ID | RESOURCE NAME | RETENTION PERIOD | DESCRIPTION |
293+
+-----+------------------------+----+---------------+------------------+-------------+
294+
| + | fasting-taussig-c9c007 | | apps | 0s | |
295+
+-----+------------------------+----+---------------+------------------+-------------+
296+
+-----+------------------------+----+---------------+------------------+-------------+
297+
| + | great-davinci-c9c005 | | new_telegraf | 0s | |
298+
+-----+------------------------+----+---------------+------------------+-------------+
299+
+-----+------------------------+----+---------------+------------------+-------------+
300+
| + | stubborn-hugle-c9c003 | | telegraf | 719h59m59s | |
301+
+-----+------------------------+----+---------------+------------------+-------------+
302+
| TOTAL | 3 |
303+
+-----+------------------------+----+---------------+------------------+-------------+
304+
```
305+
306+
Now, you have all the resources from your old instance stored in your new instance.
307+
Sign in to your new instance (by default http://localhost:8086) and take a look.
308+
You will see dashboards, but you haven't yet migrated your old data.
309+
310+
## 8. Set up integrations to point to new instance
311+
312+
Re-enable any integrations you disabled in step 2.
313+
You will need to re-enable Telegraf, client libraries, custom applications,
314+
or third-party data sinks using new tokens and credentials.
315+
316+
## 9. Load historical data into new instance
317+
318+
Use the CLI to export and then re-import your data using the command below.
319+
(For the range, pick a time before your bucket's retention period, or something a really long time ago if you have an unlimited retention period.)
320+
321+
<!--pytest.mark.skip-->
322+
323+
```sh
324+
influx query -c influx_old \
325+
'from(bucket: "my-bucket") |> range(start: -3y)' --raw > my-bucket.csv
326+
```
327+
328+
Then write to the new bucket:
329+
330+
<!--pytest.mark.skip-->
331+
332+
```sh
333+
influx write -c default --format csv -b my-bucket -f my-bucket.csv
334+
```
335+
336+
Repeat that process for each bucket.
337+
338+
## Verify InfluxDB resources, data, and integrations
339+
340+
Verify that the latest version of InfluxDB is running with all your resources, data, and integrations configured.
341+
Double-check that everything is there and it is working as expected.
342+
Once you're set up with the latest InfluxDB, you can safely turn off your old instance and archive the previous data directory.
343+
344+
## Upgrade to the latest InfluxDB v2 version
345+
346+
Follow steps to [upgrade from InfluxDB 2.0 to the latest InfluxDB 2.x version](/influxdb/v2/install/upgrade/v2-to-v2/).

0 commit comments

Comments
 (0)