DataKit Upgrade¶

DataKit supports both manual and automatic upgrade.

Requirements¶

• Automatic upgrade require DataKit version >= 1.1.6-rc1
• There is no version requirement for manual upgrade

2.x and 1.x Upgrade Policy¶

• Auto-upgrade targets the latest 2.x by default.
• If the host is already running 2.x, DataKit continues upgrading to the latest 2.x available in the configured upgrade source.
• If the upgrade source is broken (for example, missing usable 2.x installer artifacts), the upgrade fails and keeps the current version unchanged.
• If you still need 1.x (for example 1.92.0), upgrade by manually specifying that exact version.

Minimum OS requirements for 2.x:

• Linux: kernel >= 3.2
• Windows: Windows 10 / Windows Server 2016 or newer
• macOS: macOS 12 or newer

2.x and 1.x use separate upgrade sources:

• https://static.truewatch.com/datakit-v2/：2.x upgrade source, recommended.
• https://static.truewatch.com/datakit/：1.x upgrade source, for legacy systems only.

The upgrade script selects the matching version line based on the current path. Auto-upgrade always uses the datakit-v2 source. Since the two paths are independently published, datakit-v2 only upgrades to the latest 2.x, and datakit only upgrades to the latest 1.x — they do not share version information. To manually upgrade to 1.x, use a versioned script (for example install-1.93.0.sh).

Manually Upgrade¶

Directly execute the following command to view the current DataKit version. If the latest version is available online, the corresponding upgrade command will be prompted, such as:

• For remote upgrade, you must upgrade DataKit to 1.5.9+
• If DataKit < 1.2.7, you can only use datakit --version
• If DataKit < 1.2.0, use the upgrade command directly

$ datakit version

       Version: 1.2.8
        Commit: e9ccdfbae4
        Branch: testing
 Build At(UTC): 2022-03-11 11:07:06
Golang Version: go version go1.18.3 linux/amd64
      Uploader: xxxxxxxxxxxxx/xxxxxxx/xxxxxxx
ReleasedInputs: all
---------------------------------------------------

Online version available: 1.2.9, commit 9f5ac898be (release at 2022-03-10 12:03:12)

Upgrade:
DK_UPGRADE=1 bash -c "$(curl -L https://static.truewatch.com/datakit-v2/install.sh)"

$ datakit.exe version

       Version: 1.2.8
        Commit: e9ccdfbae4
        Branch: testing
 Build At(UTC): 2022-03-11 11:07:36
Golang Version: go version go1.18.3 linux/amd64
      Uploader: xxxxxxxxxxxxx/xxxxxxx/xxxxxxx
ReleasedInputs: all
---------------------------------------------------

Online version available: 1.2.9, commit 9f5ac898be (release at 2022-03-10 12:03:12)

Upgrade:
Remove-Item -ErrorAction SilentlyContinue Env:DK_*;
$env:DK_UPGRADE="1";
Set-ExecutionPolicy Bypass -scope Process -Force;
Import-Module bitstransfer;
start-bitstransfer  -source https://static.truewatch.com/datakit-v2/install.ps1 -destination .install.ps1;
powershell ./.install.ps1;

If the DataKit is currently in proxy mode, the proxy settings will be automatically added to the prompt command of automatic upgrade:

HTTPS_PROXY=http://10.100.64.198:9530 DK_UPGRADE=1 ...

$env:HTTPS_PROXY="http://10.100.64.198:9530"; $env:DK_UPGRADE="1" ...

Remote Update Service¶

Version-1.5.9 · Experimental

Note: The service does not support DataKit installed in k8s.

During the installation of DataKit, an additional upgrade management service is installed by default, which is specifically used to manage and upgrade the DataKit version. If you are using an older version of DataKit, you can specify additional parameters in the DataKit upgrade command to install this service:

DK_UPGRADE=1 \
  DK_UPGRADE_MANAGER=1 \
  bash -c "$(curl -L https://static.truewatch.com/datakit-v2/install.sh)"

DK_UPGRADE=1 \
  DK_UPGRADE_MANAGER=1 \
  DK_INSTALLER_BASE_URL="http://my.static.com/datakit" \
  bash -c "$(curl -L https://static.truewatch.com/datakit-v2/install.sh)"

You can use DCA to achieve remote updates, see DCA Documentation.

Offline Upgrade¶

Please refer to Offline Install related sections.

DataKit Version Downgrade¶

If the new version is unsatisfactory and eager to roll back the recovery function of the old version, you can directly reverse upgrade in the following ways:

DK_UPGRADE=1 bash -c "$(curl -L https://static.truewatch.com/datakit-v2/install1.2.3.sh)"

Remove-Item -ErrorAction SilentlyContinue Env:DK_*;
$env:DK_UPGRADE="1";
Set-ExecutionPolicy Bypass -scope Process -Force;
Import-Module bitstransfer;
start-bitstransfer  -source https://static.truewatch.com/datakit-v2/install1.2.3.ps1 -destination .install.ps1;
powershell ./.install.ps1;

For example, to manually upgrade to 1.93.0:

DK_UPGRADE=1 bash -c "$(curl -L https://static.truewatch.com/datakit/install-1.93.0.sh)"

$env:DK_UPGRADE="1";
Set-ExecutionPolicy Bypass -Scope Process -Force;
Import-Module bitstransfer;
Start-BitsTransfer -Source https://static.truewatch.com/datakit/install-1.93.0.ps1 -Destination .install.ps1;
powershell ./.install.ps1;

Replace 1.93.0 with any target 1.x version you need.

The version number here can be found on the DataKit release history page. Currently, only rollback to 1.2.0 is supported, and previous rc versions do not recommend rollback. After rolling back the version, you may encounter some configurations that are only available in the new version, which cannot be resolved in the rolled back version. For the time being, you can only manually adjust the configuration to adapt to the old version of DataKit.

FAQ¶

Differences Between Updating and Installing¶

To upgrade to a newer version of DataKit, you can do so by:

• Reinstallation
• Executing the upgrade command

On a host where DataKit is already installed, it is recommended to upgrade to a newer version using the upgrade command rather than reinstalling. If you reinstall, all configurations in datakit.conf will be reset to their default settings, such as global tag configurations, port settings, and so on. This may not be desirable.

However, whether you reinstall or execute the upgrade command, all the collectors(inputs) configurations are not reset to default.

Version Detection Failed Processing¶

During the DataKit installation/upgrade process, the installer detects the currently running version of the DataKit to ensure that the version is the upgraded version.

However, in some cases, the older version of the DataKit service did not uninstall successfully, resulting in the detection process discovering that the current running DataKit version number is still the older version number:

2022-09-22T21:20:35.967+0800    ERROR   installer  installer/main.go:374  checkIsNewVersion: current version: 1.4.13, expect 1.4.16

At this point, we can force the old version of DataKit to stop and restart the DataKit:

datakit service stop  # Stop service
datakit service start # Start a new service

# If not, uninstall the DataKit service and then reinstall the service
datakit service uninstall # uninstall service
datakit service reinstall # reinstall service

# After the above operations are completed, confirm whether the next DataKit version is the latest version

datakit version # Confirm that the current running DataKit is the latest version

       Version: 1.4.16
        Commit: 1357544bd6
        Branch: master
 Build At(UTC): 2022-09-20 11:43:20
Golang Version: go version go1.18.3 linux/amd64
      Uploader: zy-infra-gitlab-prod-runner/root/xxx
ReleasedInputs: checked