Merge pull request #4863 from dokku/scheduler-docs

Clarify what is necessary for implementing a scheduler plugin

docs/deployment/schedulers/alternate-schedulers.md

@@ -1,10 +0,0 @@
-# Alternative Schedulers
-
-In addition to the built-in [docker-local scheduler](/docs/advanced-usage/schedulers/docker-local.md), Dokku also supports two scheduler plugins:
-
-- [Kubernetes](https://github.com/dokku/dokku-scheduler-kubernetes)
-- [Nomad](https://github.com/dokku/dokku-scheduler-nomad)
-
-These scheduler implementations may not be complete, though provide enough functionality for a user to get an app deployed via the underlying scheduler.
-
-For users that require additional functionality, please refer to the [Sponsoring Documentation](https://github.com/dokku/.github/blob/master/SPONSORING.md).

docs/deployment/schedulers/docker-local.md

@@ -95,24 +95,15 @@ Note that increasing the value of `max_parallel` may significantly impact CPU ut
 
 This plugin implements various functionality through `plugn` triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the `scheduler-docker-local` plugin.
 
-- `check-deploy`
-- `core-post-deploy`
-- `post-app-clone-setup`
-- `post-app-rename-setup`
-- `post-create`
-- `post-delete`
-- `pre-deploy`
-- `pre-restore`
-- `scheduler-app-status`
-- `scheduler-deploy`
-- `scheduler-docker-cleanup`
-- `scheduler-inspect`
-- `scheduler-is-deployed`
-- `scheduler-logs`
-- `scheduler-logs-failed`
-- `scheduler-retire`
-- `scheduler-run`
-- `scheduler-stop`
+- `apps:clone`
+- `apps:destroy`
+- `apps:rename`
+- `deploy`
+- `enter`
+- `logs`
+- `ps:inspect`
+- `ps:stop`
+- `run`
 
 ## Supported Resource Management Properties
 

docs/deployment/schedulers/kubernetes.md

@@ -0,0 +1,14 @@
+# Kubernetes Scheduler
+
+> Warning: This scheduler is not in Dokku core and thus is considered experimental.
+
+The [Kubernetes Scheduler Plugin](https://github.com/dokku/dokku-scheduler-kubernetes) implements the following functionality:
+
+- `apps:destroy`
+- `deploy`: partial, does not implement failed deploy log capture
+- `logs`: partial, does not implement failure logs
+- `ps:stop`
+
+Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-kubernetes/issues) for more information on the status of the plugin.
+
+For users that require additional functionality, please refer to the [Sponsoring Documentation](https://github.com/dokku/.github/blob/master/SPONSORING.md).

docs/deployment/schedulers/nomad.md

@@ -0,0 +1,13 @@
+# Nomad Scheduler
+
+> Warning: This scheduler is not in Dokku core and thus is considered experimental.
+
+The [Nomad Scheduler Plugin](https://github.com/dokku/dokku-scheduler-nomad) implements the following functionality:
+
+- `apps:destroy`
+- `deploy`
+- `ps:stop`
+
+Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-nomad/issues) for more information on the status of the plugin.
+
+For users that require additional functionality, please refer to the [Sponsoring Documentation](https://github.com/dokku/.github/blob/master/SPONSORING.md).

docs/deployment/schedulers/scheduler-management.md

@@ -86,31 +86,33 @@ You can pass flags which will output only the value of the specific information
 dokku scheduler:report node-js-app --scheduler-selected
 ```
 
-### Custom schedulers
-
-To create a custom scheduler, the following triggers may be implemented:
-
-- `check-deploy`
-- `core-post-deploy`
-- `post-app-clone-setup`
-- `post-app-rename-setup`
-- `post-create`
-- `post-delete`
-- `pre-deploy`
-- `pre-restore`
-- `scheduler-app-status`
-- `scheduler-deploy`
-- `scheduler-docker-cleanup`
-- `scheduler-inspect`
-- `scheduler-is-deployed`
-- `scheduler-logs`
-- `scheduler-logs-failed`
-- `scheduler-retire`
-- `scheduler-run`
-- `scheduler-stop`
-- `scheduler-tags-create`
-- `scheduler-tags-destroy`
+## Implementing a Scheduler
 
 Custom plugins names _must_ have the prefix `scheduler-` or scheduler overriding via `scheduler:set` may not function as expected.
 
+At this time, the following dokku commands are used to implement a complete scheduler.
+
+- `apps:destroy`: stops the app processes on the scheduler
+  - triggers: post-delete, scheduler-register-retired, scheduler-retire
+- `apps:rename`: handles app renaming
+  - triggers: post-app-rename-setup
+- `apps:clone`: handles app cloning
+  - triggers: post-app-clone-setup
+- `deploy`: deploys app proceses and checks the status of a deploy
+  - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed
+- `enter`: enters a running container
+  - triggers: scheduler-enter
+- `logs`: fetches app logs
+  - triggers: scheduler-logs
+- `run`: starts one-off run containers (detached and non-detached) as well as listing run processes
+  - triggers: scheduler-run, scheduler-run-list
+- `ps:stop`: stops app processes
+  - triggers: scheduler-stop
+- `ps:inspect`: outputs inspect output for processes in an app
+  - triggers: scheduler-inspect
+
+Schedulers may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. Additionally, a scheduler may implement other triggers in order handle any extra processes needed during a deploy.
+
 Schedulers can use any tools available on the system to build the docker image, and may even be used to interact with off-server systems. The only current requirement is that the scheduler must have access to the image built in the build phase. If this is not the case, the registry plugin can be used to push the image to a registry that the scheduler software can access.
+
+Deployment tasks are currently executed directly on the primary Dokku server.

docs/template.html

@@ -160,6 +160,8 @@
 
             <a href="/{{NAME}}/deployment/schedulers/scheduler-management/" class="list-group-item">Scheduler Management</a>
             <a href="/{{NAME}}/deployment/schedulers/docker-local/" class="list-group-item">Docker Local</a>
+            <a href="/{{NAME}}/deployment/schedulers/kubernetes/" class="list-group-item">Kubernetes</a>
+            <a href="/{{NAME}}/deployment/schedulers/nomad/" class="list-group-item">Nomad</a>
             <a href="/{{NAME}}/deployment/schedulers/null/" class="list-group-item">Null Scheduler</a>
             <a href="/{{NAME}}/deployment/schedulers/alternate-schedulers/" class="list-group-item">Alternate Schedulers</a>
 

docs/viewdocs.json

@@ -41,8 +41,9 @@
     "dokku-events-logs": "advanced-usage/event-logs/",
     "dokku-storage": "advanced-usage/persistent-storage/",
 
-    "advanced-usage/schedulers/alternate-schedulers": "deployment/schedulers/alternate-schedulers",
-    "advanced-usage/schedulers/docker-local": "deployment/schedulers/docker-local",
+    "advanced-usage/schedulers/alternate-schedulers": "deployment/schedulers/scheduler-management/",
+    "advanced-usage/schedulers/docker-local": "deployment/schedulers/docker-local/",
+    "deployment/schedulers/alternate-schedulers": "deployment/schedulers/scheduler-management/",
 
     "community/tutorials/deploying-with-gitlab-ci": "deployment/continuous-integration/gitlab-ci/",