InfluxDB: Update for InfluxDB 3, condense, add metadata #2600
Conversation
jstirnaman
force-pushed
the
jts-update-influxdb
branch
6 times, most recently
from
bb33542 to
5f5128c
Compare
- Updated Docker documentation for InfluxDB 3 Core and Enterprise - Docker Compose examples - Support channel preferences - Shorten version docs to startup essentials and link to full documentation - Categories and other metadata Co-authored-by: meelahme <[email protected]>
jstirnaman
force-pushed
the
jts-update-influxdb
branch
from
5f5128c to
f9b7c2b
Compare
|
Generated README.md: <!--
********************************************************************************
WARNING:
DO NOT EDIT "influxdb/README.md"
IT IS AUTO-GENERATED
(from the other files in "influxdb/" combined with a set of templates)
********************************************************************************
-->
# Quick reference
- **Maintained by**:
[InfluxData](https://github.com/influxdata/influxdata-docker)
- **Where to get help**:
[InfluxDB Discord Server](https://discord.gg/9zaNCW2PRT) *(preferred for **InfluxDB 3 Core**, **InfluxDB 3 Enterprise**)*, [InfluxDB Community Slack](https://influxdata.com/slack) *(preferred for **InfluxDB v2**, **v1**)\*
# Supported tags and respective `Dockerfile` links
- [`1.11`, `1.11.8`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/Dockerfile)
- [`1.11-alpine`, `1.11.8-alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/alpine/Dockerfile)
- [`1.10-data`, `1.10.8-data`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.10/data/Dockerfile)
- [`1.10-data-alpine`, `1.10.8-data-alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.10/data/alpine/Dockerfile)
- [`1.10-meta`, `1.10.8-meta`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.10/meta/Dockerfile)
- [`1.10-meta-alpine`, `1.10.8-meta-alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.10/meta/alpine/Dockerfile)
- [`1.11-data`, `1.11.8-data`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/data/Dockerfile)
- [`1.11-data-alpine`, `1.11.8-data-alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/data/alpine/Dockerfile)
- [`1.11-meta`, `1.11.8-meta`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/meta/Dockerfile)
- [`1.11-meta-alpine`, `1.11.8-meta-alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/1.11/meta/alpine/Dockerfile)
- [`2`, `2.7`, `2.7.12`, `latest`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/2.7/Dockerfile)
- [`2-alpine`, `2.7-alpine`, `2.7.12-alpine`, `alpine`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/2.7/alpine/Dockerfile)
- [`3-core`, `3.2-core`, `3.2.1-core`, `core`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/3.2-core/Dockerfile)
- [`3-enterprise`, `3.2-enterprise`, `3.2.1-enterprise`, `enterprise`](https://github.com/influxdata/influxdata-docker/blob/45b1761a3dd6bf6c2923d9c9b34374a11f2b33e7/influxdb/3.2-enterprise/Dockerfile)
# Quick reference (cont.)
- **Where to file issues**:
[https://github.com/influxdata/influxdata-docker/issues](https://github.com/influxdata/influxdata-docker/issues?q=)
- **Supported architectures**: ([more info](https://github.com/docker-library/official-images#architectures-other-than-amd64))
`amd64`, `arm64v8`
- **Published image artifact details**:
[repo-info repo's `repos/influxdb/` directory](https://github.com/docker-library/repo-info/blob/master/repos/influxdb) ([history](https://github.com/docker-library/repo-info/commits/master/repos/influxdb))
(image metadata, transfer size, etc)
- **Image updates**:
[official-images repo's `library/influxdb` label](https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Finfluxdb)
[official-images repo's `library/influxdb` file](https://github.com/docker-library/official-images/blob/master/library/influxdb) ([history](https://github.com/docker-library/official-images/commits/master/library/influxdb))
- **Source of this description**:
[docs repo's `influxdb/` directory](https://github.com/docker-library/docs/tree/master/influxdb) ([history](https://github.com/docker-library/docs/commits/master/influxdb))
# What is InfluxDB?
InfluxDB is the time series database platform designed to collect, store, and process large amounts of event and time series data. Ideal for monitoring (sensors, servers, applications, networks), financial analytics, and behavioral tracking.
**This README covers all currently supported versions of InfluxDB:**
- InfluxDB 3 Core: `influxdb:3-core`
- InfluxDB 3 Enterprise: `influxdb:3-enterprise`
- InfluxDB v2: `influxdb:2`
- InfluxDB v1: `influxdb:1.11`
- InfluxDB Enterprise v1: `influxdb:1.11-data` and `influxdb:1.11-meta`
Find a specific InfluxDB version below for startup examples and links to full documentation.
## How to use InfluxDB 3 images
InfluxDB 3 is the latest version and features Apache Arrow, DataFusion SQL, and object storage for sub-10ms queries and unlimited cardinality. The InfluxDB 3 Core and InfluxDB 3 Enterprise editions both support SQL and InfluxQL queries, include the Python processing engine, and work with the InfluxDB 3 Explorer UI.
- **Core** (free, open source): For real-time monitoring and recent data
- **Enterprise**: Adds historical data, clustering, HA, and security. Includes 30-day trial.
### Pull the Image
Pull the official Docker image for InfluxDB 3 Core or InfluxDB 3 Enterprise:
**InfluxDB 3 Core:**
```bash
docker pull influxdb:3-coreInfluxDB 3 Enterprise: docker pull influxdb:3-enterpriseStart InfluxDB 3... via Example # compose.yaml
name: influxdb3
services:
influxdb3-core:
container_name: influxdb3-core
image: influxdb:3-core
ports:
- 8282:8181
command:
- influxdb3
- serve
- --node-id=node0
- --object-store=file
- --data-dir=/var/lib/influxdb3/data
- --plugin-dir=/var/lib/influxdb3/plugins
volumes:
- type: bind
source: ~/.influxdb3/core/data
target: /var/lib/influxdb3/data
- type: bind
source: ~/.influxdb3/core/plugins
target: /var/lib/influxdb3/plugins
influxdb3-enterprise:
container_name: influxdb3-enterprise
image: influxdb:3-enterprise
ports:
- 8181:8181
command:
- influxdb3
- serve
- --node-id=node0
- --cluster-id=cluster0
- --object-store=file
- --data-dir=/var/lib/influxdb3/data
- --plugin-dir=/var/lib/influxdb3/plugins
environment:
- INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=EMAIL_ADDRESS
volumes:
- type: bind
source: ~/.influxdb3/enterprise/data
target: /var/lib/influxdb3/data
- type: bind
source: ~/.influxdb3/enterprise/plugins
target: /var/lib/influxdb3/pluginsThe example InfluxDB 3 Core: docker compose run influxdb3-coreInfluxDB 3 Enterprise: *License key for Enterprise: InfluxDB 3 Enterprise requires a license key. In the example, configure your email address to start the free 30-day trial. For more options, see the InfluxDB 3 Enterprise licensing documentation.* docker compose run influxdb3-enterprise... via Use the following commands to start InfluxDB 3 Core or InfluxDB 3 Enterprise using the Docker CLI: InfluxDB 3 Core: docker run -d --name influxdb3-core \
--publish 8181:8181 \
--volume /path/on/host:/path/in/container \
influxdb:3-core influxdb3 serve \
--node-id node0 \
--object-store file \
--data-dir /path/in/containerInfluxDB 3 Enterprise: *License key for Enterprise: InfluxDB 3 Enterprise requires a license key. In the example, configure your email address to start the free 30-day trial. For more options, see the InfluxDB 3 Enterprise licensing documentation.* docker run -d --name influxdb3-enterprise \
--publish 8181:8181 \
--volume /path/on/host:/path/in/container \
influxdb:3-enterprise influxdb3 serve \
--node-id node0 \
--cluster-id cluster0 \
--object-store file \
--data-dir /path/in/container \
--license-email EMAIL_ADDRESSFor more information about server options, access the documentation: docker run --rm influxdb:3-core influxdb3 serve --helpdocker run --rm influxdb:3-enterprise influxdb3 serve --helpGet started using InfluxDB 3After you have started your InfluxDB 3 server, follow the step-by-step guides to create an auth token and database, and write, query, and process data in InfluxDB 3:
How to use the InfluxDB v2 imageInfluxDB v2 is an earlier version of InfluxDB OSS. InfluxDB 3 Core is the latest stable version. Run InfluxDB v2 using the Docker CLI with the following command: docker run -d -p 8086:8086 \
-v $PWD/data:/var/lib/influxdb2 \
-v $PWD/config:/etc/influxdb2 \
-e DOCKER_INFLUXDB_INIT_MODE=setup \
-e DOCKER_INFLUXDB_INIT_USERNAME=my-user \
-e DOCKER_INFLUXDB_INIT_PASSWORD=my-password \
-e DOCKER_INFLUXDB_INIT_ORG=my-org \
-e DOCKER_INFLUXDB_INIT_BUCKET=my-bucket \
influxdb:2After the container starts, visit http://localhost:8086 in your browser to view the UI. For detailed instructions, see the InfluxDB v2 Docker Compose documentation. For more information about How to use the InfluxDB v1 Docker imageInfluxDB v1 is an earlier version of InfluxDB OSS. InfluxDB 3 Core is the latest stable version. Run InfluxDB v1 using the Docker CLI: docker run -d -p 8086:8086 \
-v $PWD:/var/lib/influxdb \
influxdb:1.11This command maps port For more information, see the InfluxDB v1 Docker documentation. How to use the InfluxDB Enterprise v1 Docker imageInfluxDB Enterprise v1 is an earlier version of InfluxDB Enterprise. InfluxDB 3 Enterprise is the latest stable version. Use the official Start InfluxDB v1 Enterprise ClusterCreate a custom Docker network for node communication: docker network create influxdbStart three meta nodes (each with a unique hostname and license key): # Meta node 0
docker run -d \
--name=influxdb-meta-0 \
--network=influxdb \
-h influxdb-meta-0 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:meta
# Meta node 1
docker run -d \
--name=influxdb-meta-1 \
--network=influxdb \
-h influxdb-meta-1 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:meta
# Meta node 2
docker run -d \
--name=influxdb-meta-2 \
--network=influxdb \
-h influxdb-meta-2 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:metaJoin meta nodes into the cluster: docker exec influxdb-meta-0 influxd-ctl add-meta influxdb-meta-1:8091
docker exec influxdb-meta-0 influxd-ctl add-meta influxdb-meta-2:8091Start data nodes: # Data node 0
docker run -d \
--name=influxdb-data-0 \
--network=influxdb \
-h influxdb-data-0 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:data
# Data node 1
docker run -d \
--name=influxdb-data-1 \
--network=influxdb \
-h influxdb-data-1 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:dataAdd data nodes to the cluster: docker exec influxdb-meta-0 influxd-ctl add-data influxdb-data-0:8088
docker exec influxdb-meta-0 influxd-ctl add-data influxdb-data-1:8088Verify cluster status: docker exec influxdb-meta-0 influxd-ctl showThis displays all registered data and meta nodes. Stop InfluxDB v1 Enterprise ContainersTo stop individual containers: docker stop influxdb-meta-0
docker stop influxdb-meta-1
docker stop influxdb-meta-2
docker stop influxdb-data-0
docker stop influxdb-data-1Restart ContainersTo restart stopped containers: docker start influxdb-meta-0
docker start influxdb-meta-1
docker start influxdb-meta-2
docker start influxdb-data-0
docker start influxdb-data-1For more information, see the InfluxDB v1 Enterprise documentation. LicenseView license information for the software contained in this image. As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained). Some additional license information which was able to be auto-detected might be found in the As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. |
|
@sanderson @bnpfeife Please review this PR (I can't seem to actually request reviews yet).
|
|
@jstirnaman Hey, this repository is part of the Docker organization (not InfluxData). I also don't have permissions to review this. So, we'll need to wait for someone from Docker to review. We'll probably just need to be patient considering the sheer volume of changes that the Docker folk must see on a daily basis. However, the changes do look good to me. I did notice that the file permissions were changed from 0644 (read) to 755 (read + execute). I am unsure, but I suspect this is a remnant from editing the files on Windows. If a reviewer requires it, I can help get these back to 644. |
There was a problem hiding this comment.
A few notes -- I don't love how much Enterprise/licensed content we've got here (especially when it's just "here's how to do it on the OSS version, and here's all the same content again but with the tiny addition for the Enterprise edition", and because Enterprise editions are already a special case in DOI that will likely not be permitted to persist much longer; https://github.com/docker-library/official-images#what-are-official-images).
Also, it looks like we need to make more use of the %%IMAGE%% template variable, and I would indeed like to see the unnecessary/incorrect executable bits on the files dropped as discussed upthread.
| - --plugin-dir=/var/lib/influxdb3/plugins | ||
| volumes: | ||
| - type: bind | ||
| source: ~/.influxdb3/core/data |
There was a problem hiding this comment.
I'm not sure I've ever seen ~ used in a compose file -- does it support this and expand it to $HOME correctly? (I'm assuming this is tested and that it does indeed do so?)
There was a problem hiding this comment.
I'm not sure I've ever seen
~used in a compose file -- does it support this and expand it to$HOMEcorrectly? (I'm assuming this is tested and that it does indeed do so?)
Yes, it has been tested and does work.
| influxdb3-enterprise: | ||
| container_name: influxdb3-enterprise | ||
| image: influxdb:3-enterprise |
There was a problem hiding this comment.
It seems weird to have this one file start up two copies of InfluxDB just to show an example of the enterprise server (which is itself already a little bit of an outlier in DOI that we'll need to address at some point; https://github.com/docker-library/official-images#what-are-official-images 🙈).
From what I can tell, the differences are minimal, so maybe a comment would suffice? Or even leaving it as an exercise for the reader to know what the changes are, given other content in the image description?
| - InfluxDB 3 Core: `influxdb:3-core` | ||
| - InfluxDB 3 Enterprise: `influxdb:3-enterprise` | ||
| - InfluxDB v2: `influxdb:2` | ||
| - InfluxDB v1: `influxdb:1.11` | ||
| - InfluxDB Enterprise v1: `influxdb:1.11-data` and `influxdb:1.11-meta` |
There was a problem hiding this comment.
All the image references in this description should use %%IMAGE%% so that they reference the appropriate repository when they're pushed to the architecture-specific repositories (https://hub.docker.com/r/amd64/influxdb for example).
Also, this seems like kind of a lot of data to stuff into this one image description, and it might be worth considering maintaining this content elsewhere (somewhere y'all control more directly) and only including the "here's how you get started" content here followed by a "go here for more details / use cases" URL. (To some extent, this PR does exactly that, but then also confusingly still includes more detail than I was expecting.)
|
|
||
| *If you run setup from within the container, InfluxDB stores `influx` CLI [connection configurations](/influxdb/v2/reference/cli/influx/#provide-required-authentication-credentials) in the container's `/etc/influxdb2/influx-configs` file.* | ||
| ### Pull the Image |
There was a problem hiding this comment.
This is the kind of extreme level of detail we usually leave out of these image descriptions because we are pretty severely limited on space on Docker Hub (where this description actually ends up), and things like "how to pull a Docker image" are kind of orthogonal / low-level assumed knowledge.
See https://hub.docker.com/_/influxdb for how this image description ends up getting unceremoniously "chopped" thanks to the 25k byte length limit.
(Also, the vast majority of actual users will not run docker pull explicitly, but will rather embed this name in a compose.yaml, Kubernetes manifest, or docker run and it will be pulled incidentally / automatically instead.)
| -e V1_AUTH_USERNAME=v1-user \ | ||
| -e V1_AUTH_PASSWORD=v1-password \ | ||
| %%IMAGE%%:2 | ||
| docker compose run influxdb3-core |
There was a problem hiding this comment.
This is another good example of the kind of really basic command that IMO it's really reasonable to expect users to be able to figure out or intuit directly from the Compose YAML and the Compose documentation instead of providing explicitly (especially since most "real" deployments will probably want to run this via compose up -d or similar so it's not attached to an active terminal, so this doesn't even represent "real" usage very accurately).
| --network=influxdb \ | ||
| -h influxdb-meta-0 \ | ||
| -e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \ | ||
| influxdb:meta |
There was a problem hiding this comment.
These generic aliases are no longer maintained, right? So this should probably be 1.11-meta instead, if the content is kept here?
Closes influxdata/docs-v2#6019
Updates and replaces PR
Coauthor: @MeelahMe