From 3150256d96bbd16d99e725fa8c897c2bbc39e116 Mon Sep 17 00:00:00 2001 From: Matthew Fisher Date: Mon, 10 Apr 2017 12:56:40 -0700 Subject: [PATCH] doc(applications): deploying add-ons --- mkdocs.yml | 1 + src/applications/deploying-addons.md | 113 +++++++++++++++++++++++++++ src/reference-guide/terms.md | 5 ++ 3 files changed, 119 insertions(+) create mode 100644 src/applications/deploying-addons.md diff --git a/mkdocs.yml b/mkdocs.yml index 17d227f8..3745b1e1 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/applications/deploying-addons.md b/src/applications/deploying-addons.md new file mode 100644 index 00000000..6237652d --- /dev/null +++ b/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 diff --git a/src/reference-guide/terms.md b/src/reference-guide/terms.md index b38c98db..b1f9e8ca 100644 --- a/src/reference-guide/terms.md +++ b/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.