Merge pull request #9227 from dokku/datastore-plugin
Ship every datastore as a core datastore plugin
This commit is contained in:
47 files changed
+736
-43
No files matched your search
@@ -190,7 +190,7 @@ Available flags:
|
||||
The following flags surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| `--build-id` | Unique identifier of the most recent build for the app |
|
||||
| `--build-kind` | Whether the record was a `build` or a `deploy` |
|
||||
| `--build-status` | Display status (`running`, `succeeded`, `failed`, `canceled`, `abandoned`); computed at read time |
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
# Datastore Management
|
||||
|
||||
```
|
||||
datastore:app-links <datastore-type> [<app>] # list all datastore service links for a given app
|
||||
datastore:backup <datastore-type> <service> <bucket-name> [--id <id>]... # create a backup of the datastore service to an existing s3 bucket
|
||||
datastore:backup-auth <datastore-type> <service> <aws-access-key-id> <aws-secret-access-key>... # set up authentication for backups on the datastore service
|
||||
datastore:backup-deauth <datastore-type> <service> [--id <id>] # remove backup authentication for the datastore service
|
||||
datastore:backup-logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent output of the scheduled backups of the service
|
||||
datastore:backup-schedule <datastore-type> <service> <schedule> <bucket-name>... # schedule a backup of the datastore service
|
||||
datastore:backup-schedule-cat <datastore-type> <service> [--id <id>] # cat the crontab line of a scheduled backup for the service
|
||||
datastore:backup-set-encryption <datastore-type> <service> <passphrase> [--id <id>] # set encryption for all future backups of datastore service
|
||||
datastore:backup-set-public-key-encryption <datastore-type> <service> <public-key-id> [--id <id>] # set GPG Public Key encryption for all future backups of datastore service
|
||||
datastore:backup-unschedule <datastore-type> <service> [--id <id>|--all] # unschedule the backup of the datastore service
|
||||
datastore:backup-unset-encryption <datastore-type> <service> [--id <id>] # unset encryption for future backups of the datastore service
|
||||
datastore:backup-unset-public-key-encryption <datastore-type> <service> [--id <id>] # unset GPG Public Key encryption for future backups of the datastore service
|
||||
datastore:clone <datastore-type> <service> <new-service> [--clone-flags...] # create container <new-name> then copy data from <name> into <new-name>
|
||||
datastore:connect <datastore-type> <service> # connect to the service via the <datastore-type> connection tool
|
||||
datastore:create <datastore-type> <service> [--create-flags...] # create a datastore service
|
||||
datastore:create-database <datastore-type> <service> <database> # create a database in the datastore service
|
||||
datastore:create-user <datastore-type> <service> <user> [<password>] # create a user in the datastore service
|
||||
datastore:destroy <datastore-type> <service> [-f|--force] # delete the datastore service/data/container if there are no links left
|
||||
datastore:destroy-database <datastore-type> <service> <database> [-f|--force] # destroy a database created in the datastore service
|
||||
datastore:destroy-user <datastore-type> <service> <user> [-f|--force] # destroy a user created in the datastore service
|
||||
datastore:enter <datastore-type> <service> # enter or run a command in a running datastore service container
|
||||
datastore:exists <datastore-type> <service> # check if the datastore service exists
|
||||
datastore:export <datastore-type> <service> [-f|--file <path>] [--force] # export a dump of the datastore service database
|
||||
datastore:expose <datastore-type> <service> <ports...> # expose a datastore service on custom host:port if provided (random port on the 0.0.0.0 interface if otherwise unspecified)
|
||||
datastore:help [<datastore-type> [<command>]] # print the help for every datastore, one datastore or one of its commands
|
||||
datastore:import <datastore-type> <service> [-f|--file <path>] # import a dump into the datastore service database
|
||||
datastore:info <datastore-type> [<service>] [--info-flags...] # print the service information
|
||||
datastore:label <datastore-type> <service> <key=value>... # add docker labels to the service container
|
||||
datastore:link <datastore-type> <service> [<app>] [--link-flags...] # link the datastore service to the app
|
||||
datastore:linked <datastore-type> <service> [<app>] # check if the datastore service is linked to an app
|
||||
datastore:links <datastore-type> <service> # list all apps linked to the datastore service
|
||||
datastore:list <datastore-type> # list all datastore services
|
||||
datastore:logs <datastore-type> <service> [-t|--tail [<tail-num>]] # print the most recent log(s) for this service
|
||||
datastore:mount <datastore-type> [--replace] <service> <source:container-dir[:options]>... # mount a host path or docker volume into the service container
|
||||
datastore:pause <datastore-type> <service> # pause a running datastore service
|
||||
datastore:promote <datastore-type> <service> [<app>] # promote service <service> as DATABASE_URL in <app>
|
||||
datastore:reexpose <datastore-type> <service> # reexpose a datastore service, applying its expose settings
|
||||
datastore:reset <datastore-type> <service> [-f|--force] # delete all data in the datastore service, keeping the service and its links
|
||||
datastore:restart <datastore-type> <service> # graceful shutdown and restart of the datastore service container
|
||||
datastore:set <datastore-type> <service> <key> [<value>]... # set or clear a property for a service
|
||||
datastore:set-user-password <datastore-type> <service> <user> [<password>]... # change the password of a user created in the datastore service
|
||||
datastore:start <datastore-type> <service> # start a previously stopped datastore service
|
||||
datastore:stop <datastore-type> <service> # stop a running datastore service
|
||||
datastore:unexpose <datastore-type> <service> # unexpose a previously exposed datastore service
|
||||
datastore:unlabel <datastore-type> [--all] <service> [<key>...] # remove one or all docker labels from the service container
|
||||
datastore:unlink <datastore-type> <service> [<app>] [-n|--no-restart] # unlink the datastore service from the app
|
||||
datastore:unmount <datastore-type> [--all] <service> [<source:container-dir>...] # remove one or all mounts from the service container
|
||||
datastore:upgrade <datastore-type> <service> [--upgrade-flags...] # upgrade service <service> to the specified versions
|
||||
datastore:version # print the version of dokku-datastore the plugin runs
|
||||
```
|
||||
|
||||
The `datastore` plugin manages datastore services such as postgres, mysql and redis, and links them to apps. Every command takes the datastore type as its first argument, and the datastores it serves are the ones the [official datastore plugins](/docs/community/plugins.md#official-plugins) provide: clickhouse, couchdb, elasticsearch, graphite, mariadb, meilisearch, memcached, mongo, mysql, nats, omnisci, postgres, pushpin, rabbitmq, redis, rethinkdb, solr and typesense.
|
||||
|
||||
The plugin is built from [dokku-datastore](https://github.com/dokku/dokku-datastore), which the official datastore plugins also run, and keeps its services in the same place they do, under `/var/lib/dokku/services`.
|
||||
|
||||
## Usage
|
||||
|
||||
### Creating and linking a service
|
||||
|
||||
A service is created with `datastore:create` and linked to an app with `datastore:link`, which sets the variable the app connects with, such as `DATABASE_URL` for postgres or `REDIS_URL` for redis, and restarts the app.
|
||||
|
||||
```shell
|
||||
dokku datastore:create postgres lollipop
|
||||
dokku datastore:link postgres lollipop node-js-app
|
||||
```
|
||||
|
||||
`datastore:unlink` removes the link, and `datastore:destroy` removes a service once nothing is linked to it.
|
||||
|
||||
```shell
|
||||
dokku datastore:unlink postgres lollipop node-js-app
|
||||
dokku datastore:destroy postgres lollipop
|
||||
```
|
||||
|
||||
Deleting an app unlinks it from every service it is linked to.
|
||||
|
||||
### Getting help
|
||||
|
||||
`datastore:help` lists the datastore types and the commands they share. Not every datastore implements every command, so the help for one datastore lists only the commands it implements, including ones only it has, such as `connect-admin` for mongo. The help for one of a datastore's commands describes its flags and shows examples.
|
||||
|
||||
```shell
|
||||
dokku datastore:help
|
||||
dokku datastore:help postgres
|
||||
dokku datastore:help postgres create
|
||||
```
|
||||
|
||||
### Scheduled backups
|
||||
|
||||
A backup scheduled with `datastore:backup-schedule` is added to the dokku crontab as a `dokku datastore:backup` command, and is managed with the [cron plugin](/docs/processes/scheduled-cron-tasks.md) like any other scheduled task.
|
||||
|
||||
```shell
|
||||
dokku datastore:backup-auth postgres lollipop AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
|
||||
dokku datastore:backup-schedule postgres lollipop "0 3 * * *" my-s3-bucket
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
Installing dokku does not pull the image of every datastore. A datastore's images are pulled the first time a command needs them, and on later installs and upgrades once the datastore has a service.
|
||||
|
||||
### Official datastore plugins
|
||||
|
||||
The official datastore plugins, such as [dokku-postgres](https://github.com/dokku/dokku-postgres), may be installed alongside the `datastore` plugin. While one is enabled, the `datastore` plugin leaves that datastore to it when dokku runs plugin triggers, such as unlinking an app that is being deleted or writing scheduled backups into the crontab. Commands for that datastore should be run through the official plugin until it is removed.
|
||||
|
||||
The `datastore` plugin does not read the datastore definitions an official plugin ships, so a host running a modified official plugin should keep using it.
|
||||
|
||||
#### Migrating from an official datastore plugin
|
||||
|
||||
Moving a datastore from its official plugin to the `datastore` plugin leaves its services, containers, data, settings and links where they are, and does not stop running services or the apps linked to them. Using postgres as an example:
|
||||
|
||||
1. Check that `dokku datastore:version` is at least the version dokku-postgres runs, which is printed by `/var/lib/dokku/data/postgres/dokku-datastore version`. If the official plugin runs a newer version, wait for a dokku release that ships it.
|
||||
2. Uninstall the official plugin.
|
||||
|
||||
```shell
|
||||
dokku plugin:uninstall postgres
|
||||
```
|
||||
|
||||
3. Run every plugin's install trigger, which sets the host up for postgres, brings its services up to date and rewrites the crontab so scheduled backups run through `dokku datastore:backup`.
|
||||
|
||||
```shell
|
||||
dokku plugin:install
|
||||
```
|
||||
|
||||
4. Change anything that runs `dokku postgres:<command> <service>` to run `dokku datastore:<command> postgres <service>`.
|
||||
|
||||
To move back, install the official plugin again from a release running at least the version `dokku datastore:version` prints.
|
||||
@@ -142,7 +142,7 @@ app2.json
|
||||
|
||||
#### `app.json` deployment tasks
|
||||
|
||||
Dokku provides limited support for the `app.json` manifest from Heroku (documentation available [here](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
|
||||
Dokku provides limited support for the `app.json` manifest from Heroku (see the [app.json schema documentation](https://devcenter.heroku.com/articles/app-json-schema)). The keys available for use with Deployment Tasks are:
|
||||
|
||||
- `scripts.dokku.predeploy`: This is run _after_ an app's docker image is built, but _before_ any containers are scheduled. Changes made to your image are committed at this phase.
|
||||
- `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase.
|
||||
|
||||
@@ -34,7 +34,7 @@ Adding or removing docker-options will not apply to any running containers, and
|
||||
|
||||
#### Supported Docker Options
|
||||
|
||||
More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
|
||||
More information on supported Docker options can be found in the [docker run reference](https://docs.docker.com/engine/reference/commandline/run/).
|
||||
|
||||
Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
|
||||
|
||||
@@ -288,7 +288,7 @@ dokku docker-options:list node-js-app --phase deploy
|
||||
The following properties are recorded internally by the docker-options plugin and are not exposed via `docker-options:report`:
|
||||
|
||||
| Property | Scope | Description | Source |
|
||||
|---|---|---|---|
|
||||
| --- | --- | --- | --- |
|
||||
| `migrated-from-files` | global | Global migration sentinel that records that the legacy `DOCKER_OPTIONS_<PHASE>` flat-file store has been drained into plugin properties | `plugins/docker-options/functions.go` writes `"true"` once the install-time migration runs |
|
||||
| `migrated-build` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_BUILD` file was drained into the `_default_.build` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
|
||||
| `migrated-deploy` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_DEPLOY` file was drained into the `_default_.deploy` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
|
||||
|
||||
@@ -172,7 +172,7 @@ dokku storage:set node-js-data chown
|
||||
The following properties can be set:
|
||||
|
||||
| Property | Description | Unsetting it means |
|
||||
|---|---|---|
|
||||
| --- | --- | --- |
|
||||
| `chown` | Ownership preset or numeric uid for the host directory | no chown is performed |
|
||||
| `mode` | Octal permissions for the host directory | permissions are left alone |
|
||||
| `namespace` | Namespace holding the PVC (k3s) | the `default` namespace |
|
||||
@@ -324,7 +324,7 @@ dokku storage:mount --replace node-js-app \
|
||||
```
|
||||
|
||||
| Token | Meaning |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| `ro` | Mount the volume read-only |
|
||||
| `rw` | Mount it read-write, the explicit opposite of `ro` and the default |
|
||||
| `volume-subpath=<path>` | Subpath within the entry |
|
||||
|
||||
@@ -283,7 +283,7 @@ dokku registry:set --global push-extra-tags
|
||||
> The `Report flags` column lists the CLI argument names accepted by `registry:report`. The JSON keys emitted by `registry:report --format json` are the same names with the leading `--registry-` stripped (e.g. `image-repo`, `global-server`, `computed-push-on-release`). Legacy keys with the `registry-` prefix (e.g. `registry-image-repo`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
|
||||
|
||||
| Property | Scope | Default | Report flags | Description |
|
||||
|---|---|---|---|---|
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `image-repo` | app only | `dokku/<app>` | `--registry-image-repo`, `--registry-computed-image-repo` | Repository name used when pushing the app's image (overrides the global template) |
|
||||
| `image-repo-template` | app + global | none | `--registry-image-repo-template`, `--registry-global-image-repo-template`, `--registry-computed-image-repo-template` | Go template used to compute the per-app image repository when `image-repo` is unset |
|
||||
| `push-extra-tags` | app + global | none | `--registry-push-extra-tags`, `--registry-global-push-extra-tags`, `--registry-computed-push-extra-tags` | Comma-separated list of additional tags pushed alongside the deploy tag |
|
||||
@@ -298,7 +298,7 @@ dokku registry:set --global push-extra-tags
|
||||
The following `registry:report` fields describe credentials created by `registry:login` and are not settable via `registry:set`.
|
||||
|
||||
| Report flag | Scope | Description |
|
||||
|---|---|---|
|
||||
| --- | --- | --- |
|
||||
| `--registry-auth-servers` | app only | Comma-separated list of servers the app has its own credentials for |
|
||||
| `--registry-global-auth-servers` | app + global | Comma-separated list of servers the global credentials cover |
|
||||
| `--registry-computed-auth-servers` | app + global | Comma-separated list of servers whose credentials would be used for the app |
|
||||
|
||||
Reference in new issue
Block a user