---
title: Test your InfluxDB Cluster
description: Test to ensure your InfluxDB cluster can write and query data successfully.
url: https://docs.influxdata.com/influxdb3/clustered/install/set-up-cluster/test-cluster/
estimated_tokens: 1499
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/clustered/install/set-up-cluster/test-cluster/
date: '2026-05-15T15:46:14-06:00'
lastmod: '2026-05-15T15:46:14-06:00'
---

* Install InfluxDB Clustered
* Phase 1: Set up your cluster

With your InfluxDB cluster deployed and running, test to ensure you can
successfully write and query data from InfluxDB.

1. [Download and install influxctl](#download-and-install-influxctl)
2. [Retrieve your cluster’s admin token](#retrieve-your-clusters-admin-token)
3. [Configure influxctl to connect to your cluster](#configure-influxctl-to-connect-to-your-cluster)
4. [Create a new database](#create-a-new-database)
5. [Write test data to the new database](#write-test-data-to-the-new-database)
6. [Query the test data from your database](#query-the-test-data-from-your-database)

## Download and install influxctl

[`influxctl`](/influxdb3/clustered/reference/cli/influxctl/) is a command line tool
that lets you manage, write data to, and query data from your InfluxDB cluster
from your local machine.

[Download and install influxctl](/influxdb3/clustered/reference/cli/influxctl/#download-and-install-influxctl)

## Retrieve your cluster’s admin token

InfluxDB Clustered generates a valid access token (known as the *admin token*)
and stores it as a secret in your cluster’s `influxdb` namespace.
During this phase of the installation process, use the admin token with`influxctl` in lieu of configuring and using an identity provider.

Use `kubectl` to retrieve the admin token from your `influxdb` namespace secret
store and copy it to a file:

```sh
kubectl get secrets/admin-token \
  --template={{.data.token}} \
  --namespace influxdb | base64 -d > token.json
```

## Configure influxctl to connect to your cluster

Create an [`influxctl` connection profile](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles)for your InfluxDB cluster. Connection profiles are stored in a `config.toml`file on your local machine and contain the credentials necessary to connect to
and authorize with your InfluxDB cluster.

1. Create a file named `config.toml` with the following contents:

   ```
   [[profile]]
     name = "default"
     product = "clustered"
     host = "cluster-host.com"
     port = "INFLUXDB_PORT"

     [profile.auth.token]
       token_file = "/DIRECTORY_PATH/token.json"
   ```

   In the example above, replace the following:

   * `INFLUXDB_PORT`:
     The port to use to connect to your InfluxDB cluster.
   * `DIRECTORY_PATH`:
     The directory path to your admin token file, `token.json`.

   > [!Note]
> To set your InfluxDB cluster host, click **Set InfluxDB cluster URL** below the codeblock above
> and provide your cluster’s host. This will update your cluster’s host in all
> code examples.

2. Make this configuration file available to `influxctl` in one of the following
   ways:

   * Include the `--config` flag with all `influxctl` commands to specify the
     filepath of your `config.toml`.
   * Store the `config.toml` file at the[default location](/influxdb3/clustered/reference/cli/influxctl/#default-connection-profile-store-location)that `influxctl` expects to find connection profiles based on your
     operating system. If your connection profile is in the default location,
     you do not need to include the `--config` flag with your `influxctl` commands.

#### Connection configuration examples

In the examples below, replace `CONFIG_PATH`with the directory path to your connection configuration file. If you placed
your configuration file in the default location for your operating system, remove`--config /CONFIG_PATH/config.toml` from the example commands before running them.

## Create a new database

Use [`influxctl database create`](/influxdb3/clustered/reference/cli/influxctl/database/create/)to create a new database named `testdb`. Include the following:

* *(Optional)* The path to your connection profile configuration file.
* The database name–`testdb`.

```sh
influxctl --config /CONFIG_PATH/config.toml database create testdb
```

## Write test data to the new database

Use [`influxctl write`](/influxdb3/clustered/reference/cli/influxctl/write/) to
write the following test data to your `testdb` database. Provide the following:

* *(Optional)* The path to your connection profile configuration file.
* The database name–`testdb`.
* [Line protocol](/influxdb3/clustered/reference/syntax/line-protocol/) to write
  to InfluxDB.

```bash
influxctl --config /CONFIG_PATH/config.toml write \
  --database testdb \
  "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000000000000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000000000000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600000000000
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600000000000
"
```

## Query the test data from your database

Use [`influxctl query`](/influxdb3/clustered/reference/cli/influxctl/query/) to
query the test data from your `testdb` database. Provide the following:

* *(Optional)* The path to your connection profile configuration file.
* The database name–`testdb`.
* The SQL query to execute.

```bash
influxctl --config /CONFIG_PATH/config.toml query \
  --database testdb \
  "SELECT * FROM home"
```

This should return results similar to:

|co |hum |   room    |temp|        time        |
|---|----|-----------|----|--------------------|
| 0 |35.9|Living Room|21.1|2022-01-01T08:00:00Z|
| 0 |35.9|  Kitchen  | 21 |2022-01-01T08:00:00Z|
| 0 |21.4|Living Room|21.4|2022-01-01T09:00:00Z|
| 0 |36.2|  Kitchen  | 23 |2022-01-01T09:00:00Z|

If the query successfully returns data, your InfluxDB cluster is set up and functional.

[Test your cluster](/influxdb3/clustered/install/set-up-cluster/test-cluster/)[Phase 2: Customize your cluster](/influxdb3/clustered/install/customize-cluster/)
| co | hum | room | temp | time |
| --- | --- | --- | --- | --- |
| co | hum | room | temp | time |
| 0 | 35.9 | Living Room | 21.1 | 2022-01-01T08:00:00Z |
| 0 | 35.9 | Kitchen | 21 | 2022-01-01T08:00:00Z |
| 0 | 21.4 | Living Room | 21.4 | 2022-01-01T09:00:00Z |
| 0 | 36.2 | Kitchen | 23 | 2022-01-01T09:00:00Z |