The DC/OS Universe contains all of the services that are installable DC/OS. For more information on DC/OS Universe, see the GitHub Universe repository.
All services in the package repositories are required to meet a certain standard as defined by Mesosphere. For details on submitting a DC/OS service, see Contributing a package.
Admin Router and web interface integration
By default, a DC/OS service is deployed on a private agent node. To allow configuration control or monitoring of a service by a user, the admin router proxies calls on the master node to the service in a private node on the cluster. The HTTP service endpoint requires relative paths for artifacts and resources. The service endpoint can provide a web interface, a RESTful endpoint, or both. When creating a DC/OS CLI subcommand it is common to have a RESTful endpoint to communicate with the scheduler service.
The integration to the admin router is automatic when a framework scheduler registers a
webui_url during the registration process with the Mesos master. There are a couple of limitations:
- The URL must NOT end with a backslash (/). For example, this is good
internal.dcos.host.name:10000, and this is bad
- DC/OS supports 1 URL and port.
webui_url is provided, the service is listed on the DC/OS web interface as a service with a link. That link is the admin router proxy URL name that is based on a naming convention of:
/service/<service_name>. For example,
<dcos_host>/service/unicorn is the proxy to the
webui_url. If you provide a web interface, it will be integrated with the DC/OS web interface and users can click the link for quick access to your service.
Service health check information is provided from the DC/OS service tab when:
- There are service health checks defined in the
marathon.json file. For example:
You can provide public access to your service through the admin router or by deploying your own proxy or router to the public agent node. It is recommend to use the admin router for scheduler configuration and control allowing integration with the DC/OS web interface. It is also recommended to provide a CLI subcommand for command-line control of a RESTful service endpoint for the scheduler.
DC/OS Service structure
Each DC/OS service contains
marathon.json files. The contents of these files are described in the DC/OS Service specification.
"name": "cassandra", parameter specified here defines the DC/OS service name in the package repository. The must be the first parameter in the file.
- Focus the description on your service. Assume that all users are familiar with DC/OS and Mesos.
tags parameter is used for user searches (
dcos package search <criteria>). Add tags that distinguish your service in some way. Avoid the following terms: Mesos, Mesosphere, DC/OS, and datacenter. For example, the unicorns service could have:
"tags": ["rainbows", "mythical"]
preInstallNotes parameter gives the user information they’ll need before starting the installation process. For example, you could explain what the resource requirements are for your service.
"preInstallNotes":"Unicorns take 7 nodes with 1 core each and 1TB of ram."
postInstallNotes parameter gives the user information they’ll need after the installation. Focus on providing a documentation URL, a tutorial, or both. For example:
"postInstallNotes": "Thank you for installing the Unicorn service.nntDocumentation: http://<your-url>ntIssues: https://github.com/",
postUninstallNotes parameter gives the user information they’ll need after an uninstall. For example, further cleanup before reinstalling again and a link to the details. A common issue is cleaning up ZooKeeper entries. For example:
postUninstallNotes": "The Unicorn DC/OS Service has been uninstalled and will no longer run.nPlease follow the instructions at http://<your-URL> to clean up any persisted state" }
- The requirement block is for all properties that are required by the marathon.json file without a condition block (it is NOT properties that are not provided and thus must be supplied by the user)
NOTE: All services submitted to the DC/OS package repositories are required to use versioned artifacts that do not change.
Creating a DC/OS Service
Here is a detailed developer workflow for creating a DC/OS service:
- Fork the Universe repository.
Create a DC/OS service in your local repository.
- Name your service. For example,
The DC/OS package repository directory structure is:
<initial-letter> is the uppercase first letter of your service name.
<service-name> is the lowercase service name. Do not use keywords such as Apache, Mesos or DC/OS in your service name.
<version> is the service version number.
- Create a directory under
repo/packages for your service. For example,
- Create a version index directory. For example,
marathon.json to your index directory.
- If you have a CLI subcommand, create a
command.json file and add to your index directory.
Test your service on DC/OS:
- Configure DC/OS to point to your local repository. For example, if your forked repository at
https://github.com/mesosphere/altuniverse and using the
version-1.x branch, add it to your DC/OS configuration with this command:
$ dcos package repo add my-repo https://github.com/mesosphere/altuniverse/archive/version-1.x.zip
Make your service public
If your service is a Marathon application, you can make it accessible to those outside the cluster by adding labels to your application definition. The DC/OS Admin Router reads these labels and exposes your app at /service/.
These labels are
DCOS_SERVICE_NAME: The name of your Marathon app.
DCOS_SERVICE_SCHEME: This can be
DCOS_SERVICE_PORT_INDEX: The port index can be any value greater than or equal to 0.
Naming and directory structure
After you add the JSON files to the index folder, there are scripts under the
Run the package repository scripts in numerical order. If a script passes you can move on to the next script.
- Run the
0-validate-version.sh script to validate the versioning.
1-validate-packages.sh script to validate the
package.json files against the schema.
2-build-index.sh script to add your DC/OS service to the
3-validate-index.sh script to validate the
For more information about the JSON files, see the Universe Readme page.