From 2df8530ede516186baa9af830a8c216cf1e84958 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 | 93 ++++++++++++++++++++++++++++ src/reference-guide/terms.md | 5 ++ 3 files changed, 99 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..e3b4ba76 --- /dev/null +++ b/src/applications/deploying-addons.md @@ -0,0 +1,93 @@ +# 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 broker][broker], 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][broker] 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][broker] 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:m4.large +``` + +If a user wishes to see all available addons, they can use `deis addons:catalog`. + +``` +$ deis addons:catalog +name description +--------------- ---------------------- +bonsai Bonsai Elasticsearch +deis-postgresql Deis Workflow Postgres +librato Librato +``` + +To view what plans are available for a given service, use `deis addons:plans `. + +``` +$ deis addons:plans deis-postgresql +name free? description +------ ----- ------------------------------------------------------------------------ +t2.micro yes 1 vCPU, 1GB memory, poor network performance. +t2.small no 1 vCPU, 2GB memory, poor network performance. +m4.large no 2 vCPUs, 8GB memory, PIOPS-Optimized, moderate network performance. +m4.xlarge no 4 vCPUs, 16GB memory, PIOPS-Optimized, high network performance. +m4.10xlarge no 40 vCPUs, 160GB memory, PIOPS-Optimized, 10 Gigabit network performance. +``` + +To see more information about the plans, use the `--raw` flag to dump the raw JSON to stdout for +future parsing with tools like [`jq`](https://stedolan.github.io/jq/). This might be useful when +the plan has more information about pricing in the metadata which cannot be cleanly parsed out in +the CLI. + +## 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. You can also check `deis addons:plans` for a high-level view of each service plan. + +For example, to provision a `m4.large` plan database: + +``` +$ deis addons:create deis-postgresql:m4.large --app wooden-rowboat +Creating deis-postgresql:m4.large... done +Binding deis-postgresql:m4.large to wooden-rowboat... done, v5 +``` + +Once the instance has been attached to the application, a DATABASE_URL environment variable will be +available in the application's environment and will contain the URL used to access the newly +provisioned service. The environment variables exposed by the instance will be viewable through +`deis config:list`. + +## Deprovisioning the Add-on + +To deprovision a `m4.large` plan database: + +``` +$ deis addons:destroy deis-postgresql:m4.large +Un-binding deis-postgresql:m4.large from wooden-rowboat... done, v6 +Destroying deis-postgresql:m4.large... done +``` + + +[broker]: ../reference-guide/terms.md#service-broker +[Open Service Broker API]: https://github.com/openservicebrokerapi/servicebroker +[service-catalog]: https://github.com/kubernetes-incubator/service-catalog 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.