doc(applications): deploying add-ons

Author: Matthew Fisher

mkdocs.yml

@@ -44,6 +44,7 @@ pages:
     - SSH Keys: users/ssh-keys.md
   - Applications:
     - Deploying Apps: applications/deploying-apps.md
+    - Deploying Add-ons: applications/deploying-addons.md
     - Buildpacks: applications/using-buildpacks.md
     - Dockerfiles: applications/using-dockerfiles.md
     - Docker Images: applications/using-docker-images.md

src/applications/deploying-addons.md

@@ -0,0 +1,113 @@
+# Deploying Add-ons
+
+The goal of `deis addons` is to give users the power to provision consumable services such as
+a postgres database, a minio bucket, or a logstash connection) to their applications. `deis addons`
+can work with both common on-premise services such as a local mysql database or a Redis server
+for a "private" or on-premise service registry, or with public SaaS applications such as MongoLab
+or Papertrail for a public service offering.
+
+`deis addons` is backed by a project called [service-catalog][]. Service-catalog brings integration
+with [service brokers][] to the Kubernetes ecosystem via the [Open Service Broker API][].
+
+Users of Workflow use `deis addons` to provision an add-on offered by [service brokers][] for
+their applications. The end-goal is to provide a way for users to consume services from brokers and
+have their applications use those services without needing detailed knowledge about how those
+services are created or managed.
+
+As an example, most applications deployed by Workflow need a data store of some kind. `deis addons`
+allows applications to consume services like databases that exist somewhere via common environment
+variables like `DATABASE_URL`.
+
+## Listing Available Add-ons
+
+A user can use `deis addons:list` to see if they have a database provisioned and what plan it is
+using.
+
+```
+$ deis addons:list | grep -i postgresql
+$ deis-postgresql:standard
+```
+
+If the application doesn’t yet have a database provisioned, a user can create a new database using
+the CLI.
+
+If a user wishes to see all available addons, they can use `deis addons:services`.
+
+```
+$ deis addons:services
+slug             name
+---------------  ----------------------
+bonsai           Bonsai Elasticsearch
+deis-postgresql  Deis Workflow Postgres
+librato          Librato
+```
+
+## Provisioning the Add-on
+
+Most service brokers offers a variety of plans, usually spread across different tiers of service:
+hobby, standard, premium, and enterprise. For a detailed breakdown on the available plans, check
+the documentation for the applicable service broker to help choose the right service tier for the
+application.
+
+For example, to provision a `standard` plan database:
+
+```
+$ deis addons:create deis-postgresql:standard --app wooden-rowboat
+Creating deis-postgresql:standard... done
+Attaching deis-postgresql:standard to wooden-rowboat... done, v5
+```
+
+Depending on the plan, some services can take some time before it becomes available for use. Use
+`deis addons:wait` to wait for the service to become available.
+
+Once the service has been attached to the application, a DATABASE_URL setting will be available in
+the application's configuration and will contain the URL used to access the newly provisioned
+service.
+
+You can choose the alias that the add-on uses on the application using the `--as` flag. This will
+affect the name of the variable the add-on adds to the application.
+
+```
+$ deis addons:attach deis-postgresql:standard --app wooden-rowboat --as POSTGRESQL_URL
+Creating deis-postgresql:standard... done
+Attaching deis-postgresql:standard to wooden-rowboat as POSTGRESQL_URL... done, v5
+```
+
+## Deprovisioning the Add-on
+
+To deprovision a `standard` plan database:
+
+```
+$ deis addons:destroy deis-postgresql:standard
+Destroying deis-postgresql:standard... done
+```
+
+## Attaching the Add-on
+
+Once the add-on is provisioned, it is bound to the user's account and can be bound to any number of
+applications the user has permissions to use.
+
+To attach an add-on to a new or existing application:
+
+```
+$ deis addons:attach deis-postgresql:standard --app wooden-rowboat
+Attaching deis-postgresql:standard to wooden-rowboat... done, v5
+```
+
+Similar to `addons:create`, you can choose the alias that the add-on uses on the application using
+the `--as` flag.
+
+## Detaching the Add-on
+
+Similarly, an add-on can be unbound from an application, but still be available to the user for
+future binding to another application.
+
+```
+$ deis addons:detach deis-postgresql:standard --app wooden-rowboat
+Detaching deis-postgresql:standard from wooden-rowboat... done, v6
+```
+
+
+[Open Service Broker API]: https://github.com/openservicebrokerapi/servicebroker
+[service-catalog]: https://github.com/kubernetes-incubator/service-catalog
+[service brokers]: ../reference-guide/terms.md#service-broker

src/reference-guide/terms.md

@@ -80,3 +80,8 @@ The Deis scheduler client is implemented in the Controller component.
 ## Service
 
 A Kubernetes Service is an abstraction which defines a logical set of Pods and a policy by which to access them. In Workflow, a Service is used to load-balance an application's [Containers](#containers) internally through a virtual IP address.
+
+
+## Service Broker
+
+A service broker is an endpoint that manages a set of plans (tiers) for a given service, such as MySQL, Postgres or Logstash.