doc(applications): deploying add-ons #791

bacongobbler · 2017-04-10T20:00:38Z

This is the design document for deis addons and is currently a work-in-progress. This document is expected to change over time as work is being done.

closes #741 once the work has been laid out and implemented.

deis-bot · 2017-04-10T20:00:41Z

@slack, @mboersma and @krancour are potential reviewers of this pull request based on my analysis of git blame information. Thanks @bacongobbler!

ultimateboy · 2017-04-10T20:18:50Z

src/applications/deploying-addons.md

+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


How would this work with a broker that has multiple credential values, such as DB_USER and DB_PASS?

This is a very good question. This is a straight cut from Heroku's docs and I'm not sure if it's a resonable effort to do this for a first pass. I'm not sure how Heroku handles this either as I know they have add-ons like Papertrail with multiple envvars. I'll go play around with some of their add-ons and see what works and what doesn't.

I was thinking we could do some crazy docker-like mapping in the form of --as DATABASE_URL=DB_URL,DATABASE_USER=DB_USER, but again I'm concerned about making the translation overly complex. I'm sure this will come into play as things start being implemented.

bacongobbler · 2017-04-10T20:26:29Z

added deis addons:services to the docs to list the service catalog.

bacongobbler · 2017-04-10T22:03:21Z

removed the --as support in the doc. Heroku's implementation is shoddy at best and I couldn't think of a perfect solution out the door, so for an initial implementation we'll just accept whatever envvars the service broker gives us.

krancour · 2017-04-11T02:04:12Z

@bacongobbler, I think one needs to carefully read docs or interactive help to understand that addons:list is provisioned and bound services while addons:services are available services. Would the intent of each of those list operations be less ambiguous if we used addons:provisioned (or addons:installed) and addons:available, respectively?

bacongobbler · 2017-04-11T02:25:22Z

I was trying to make it a 1:1 mapping with heroku CLI commands, but I agree it is a little confusing. I'd be amenable to deis addons:list being the catalog list and deis addons:installed being a list of addons provisioned under the user's account. How about that?

krancour · 2017-04-11T02:42:56Z

Is parity with Heroku still a concrete objective? In either event, I'm happy with what you have just proposed.

mboersma · 2017-04-11T15:17:09Z

Is parity with Heroku still a concrete objective?

Yes, because it's still a familiar toolset to many people, and that's still the general inspiration for Deis Workflow functionality. But it's not set in stone, if there's a good argument for doing things a different way--and it sounds like there might be here.

bacongobbler · 2017-04-11T15:18:57Z

I think this is a very good opportunity to change the heroku CLI names for specific commands. I agree that addons:list and addons:services is too confusing. I'll update the docs with the commands I proposed.

bacongobbler · 2017-04-12T21:35:57Z

So as it turns out, instances are namespaced. Makes sense, but we haven't had to provision user-namespaced resources before... Everything was either an annotation on the application's service or on the router.

What I think that means going forward is that we can introduce a myuser namespace creation at deis register (along with a data migration for existing users), then each instance that is provisioned from a broker is created in that user's namespace. Instance bindings just reference instances by name which is globally unique, so having the instance in one namespace and the binding in another shouldn't matter, right? This would also have the added benefit that all instances are removed when the user is deleted. This would also be a useful transition into deis teams, in that instances are deployed to a team's namespace and can be managed by the cluster operator accordingly.

Any opinions/thoughts on the matter, @krancour or @ultimateboy?

bacongobbler · 2017-04-12T22:48:08Z

From what it looks like, my assumption was wrong. instances and instance bindings must exist in the same namespace, so instances must be bound to the application then. That kinda sucks, because I had expected instances to be able to bind to an account and the bindings would be what the application cares about. I'll file a ticket upstream and see if there's a way we can work around this.

As seen here, I have an instance in the bacongobbler namespace...

><> kubectl --context=service-catalog get instances --namespace bacongobbler
NAME           KIND
ups-instance   Instance.v1alpha1.servicecatalog.k8s.io

...And an instance binding in the test-ns namespace following the basic walkthrough.

><> kubectl --context=service-catalog get bindings -n test-ns ups-binding -o yaml
apiVersion: servicecatalog.k8s.io/v1alpha1
kind: Binding
metadata:
  creationTimestamp: 2017-04-12T22:44:01Z
  finalizers:
  - kubernetes
  name: ups-binding
  namespace: test-ns
  resourceVersion: "76"
  selfLink: /apis/servicecatalog.k8s.io/v1alpha1/namespaces/test-ns/bindings/ups-binding
  uid: 85e8d1d6-1fd1-11e7-b4a0-0242ac110006
spec:
  instanceRef:
    name: ups-instance
  osbGuid: 17633cb4-dff1-4221-909d-e3dadc2f3707
  secretName: my-secret
status:
  conditions:
  - message: The binding references an Instance that does not exist. Binding "test-ns/ups-binding"
      references a non-existent Instance "test-ns/ups-instance"
    reason: ReferencesNonexistentInstance
    status: "False"
    type: Ready

bacongobbler · 2017-04-12T22:59:04Z

You know what, the idea of the instance and the instance binding living in the same namespace makes more sense anyways because in a team-centric world, all apps will be deployed in the same namespace as the team name so the instance should live in there.

I'll be white-boarding this more overnight and try to come up with a better solution tomorrow.

arschles

I added a bunch of my $0.02 here 😄

arschles · 2017-04-12T22:58:48Z

src/applications/deploying-addons.md

+---------------  ----------------------
+bonsai           Bonsai Elasticsearch
+deis-postgresql  Deis Workflow Postgres
+librato          Librato


Does this list imply that the available services are provided as slugs? I have so many other questions, but I'll leave it at that for now 😄

Yep! The slug and name field relate directly with a service class' name and the description field. I'll change the name field to description and slug to name to hopefully make things clearer. This is just how Heroku calls things.

So given the ups broker is installed, deis addons:catalog would look like:

name description --------------------- --------------------- user-provided-service User Provided Service

arschles · 2017-04-12T23:00:02Z

src/applications/deploying-addons.md

+```
+$ deis addons:detach deis-postgresql:standard --app wooden-rowboat
+Detaching deis-postgresql:standard from wooden-rowboat... done, v6
+```


what do you want to happen when a detach (unbind) happens before a deprovision?

So let's think about this in a team-oriented fashion:

I have a team (a namespace to store all apps deployed by a team)

I have many apps deployed in this namespace

I have a few instances running in this namespace

I would expect that, as a user, I can bind an app to the instance as well as unbind apps from the instance.

This is essentially useless for the "instance in the app's namespace" use case though. Again I'll give this some more thought. :)

arschles · 2017-04-12T23:01:57Z

src/applications/deploying-addons.md

+```
+
+If the application doesn’t yet have a database provisioned, a user can create a new database using
+the CLI.


This is a little confusing. Does this phrase:

a user can create a new database using the CLI

Refer to a provision operation?

Correct. It relates to an instance resource being created on the service-catalog's side.

Basically there are three operations:

list the catalog

CRUD the instances

CRUD the instance bindings

arschles · 2017-04-12T23:02:36Z

src/applications/deploying-addons.md

+is using.
+
+```
+$ deis addons:installed | grep -i postgresql


How does someone get a new addon into this list? In service-catalog land, they'd do that by creating a Broker resource. Is there an analog with the deis CLI?

There is not. The expectation is that we will be listing the service classes, but the brokers themselves is managed by service-catalog and we are not adding any administration to service catalog. Just communicating with it similar to how we consume the kubernetes API.

So basically if an admin creates a new broker resource, it will populate new service classes into the mix for users to query via deis addons:catalog

I haven't added addons:catalog into the docs yet but I am going to amend these once again so users can list instances, bindings and service classes.

arschles · 2017-04-12T23:03:33Z

src/applications/deploying-addons.md

+# 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`


The closing ) doesn't have an opening one to match.

arschles · 2017-04-12T23:05:04Z

src/applications/deploying-addons.md

+
+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`.


Is there a way for the app developer (the person who executes deis addons:attach for example) to tell what env vars are available, after they do the attach operation (note there's no way in service-catalog land to tell what's available before the attach)?

I know that Heroku exposes them in config:list. I'm sure we can do the same somehow.

added more context lower down; should be available through deis config:list.

krancour · 2017-04-13T00:25:11Z

@bacongobbler whether it should be possible to bind to instances in other namespaces was the subject of lots and lots of discussion very early on, but not so much as of late. I am of the opinion that in large enterprises and in microservice architectures, the notion of n applications all binding to a common instance that belongs to none of them (but is managed as its own thing) is probably not an uncommon use case. But that's not something that service catalog currently does because it would simply defy k8s existing permissions model and I don't think we were about to go re-inventing that.

The practical implication of that is exactly what you seem to have concluded already-- that service instances and bindings for those instances should all be provisioned within an app's own namespace (or within a team namespace that contains multiple apps? is that a thing now?)

Also, since Workflow is very app centric, would provision + bind be combined into a single step for Workflow users?

bacongobbler · 2017-04-13T19:27:10Z

or within a team namespace that contains multiple apps? is that a thing now?

Nope! Just a twinkle in my eye.

Also, since Workflow is very app centric, would provision + bind be combined into a single step for Workflow users?

Yes. Honestly I've just revamped the documentation again to only have 5 commands:

addons:list (list instances provisioned for this app)
addons:create (create an instance + binding, using format serviceclassname:plan as argument)
addons:destroy (destroy an instance + binding using service class name as the argument)
addons:catalog (list available service classes)
addons:plans (list available plans for the given service class name)

addons:plans is still yet to be added to this PR, but will be up in a sec.

At the current time let's keep the instance + instance binding together with the app since all apps are in their own namespace. Had we deployed apps in a user's personal namespace (or implemented deis teams) then separating instance bindings from the app might've made more sense, but not with the current model.

krancour · 2017-04-13T19:42:04Z

src/applications/deploying-addons.md

+Attaching deis-postgresql:standard to wooden-rowboat... done, v5
+```
+
+Once the instance has been attached to the application, a DATABASE_URL setting will be available in


"setting" is a bit ambiguous. Change to "environment variable"?

krancour · 2017-04-13T19:45:56Z

@bacongobbler I like where this is headed. It's clean and simple. There's a lot more complexity that could be exposed, but given Workflow's Heroku-esque focus on 12factor apps, this looks to be just right. 💯

bacongobbler · 2017-04-13T20:02:18Z

k, deis addons:plans has now been added as well.

bacongobbler added docs in progress labels Apr 10, 2017

bacongobbler force-pushed the addons branch from 8f6a91a to 0f335f9 Compare April 10, 2017 20:04

ultimateboy reviewed Apr 10, 2017

View reviewed changes

bacongobbler force-pushed the addons branch from 0f335f9 to 3150256 Compare April 10, 2017 20:26

bacongobbler force-pushed the addons branch from 3150256 to b959979 Compare April 10, 2017 22:02

bacongobbler force-pushed the addons branch from b959979 to 9b6d484 Compare April 11, 2017 15:20

arschles reviewed Apr 12, 2017

View reviewed changes

bacongobbler force-pushed the addons branch 3 times, most recently from c42dcd1 to 4576979 Compare April 13, 2017 19:19

krancour reviewed Apr 13, 2017

View reviewed changes

bacongobbler force-pushed the addons branch 2 times, most recently from d2e5145 to 9d3ff15 Compare April 13, 2017 20:01

bacongobbler force-pushed the addons branch from 9d3ff15 to 32b6e41 Compare April 13, 2017 20:14

bacongobbler force-pushed the addons branch 2 times, most recently from c0f6cc7 to 1360c72 Compare April 13, 2017 20:25

doc(applications): deploying add-ons

2df8530

bacongobbler force-pushed the addons branch from 1360c72 to 2df8530 Compare April 13, 2017 20:26

mboersma added the proposal label Aug 1, 2017

mboersma added help wanted and removed in progress labels Aug 9, 2017

doc(applications): deploying add-ons #791

Are you sure you want to change the base?

doc(applications): deploying add-ons #791

Conversation

bacongobbler commented Apr 10, 2017

deis-bot commented Apr 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bacongobbler commented Apr 10, 2017

bacongobbler commented Apr 10, 2017 • edited

krancour commented Apr 11, 2017

bacongobbler commented Apr 11, 2017 • edited

krancour commented Apr 11, 2017

mboersma commented Apr 11, 2017

bacongobbler commented Apr 11, 2017

bacongobbler commented Apr 12, 2017 • edited

bacongobbler commented Apr 12, 2017 • edited

bacongobbler commented Apr 12, 2017

arschles left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bacongobbler Apr 13, 2017 • edited

Choose a reason for hiding this comment

bacongobbler Apr 13, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krancour commented Apr 13, 2017

bacongobbler commented Apr 13, 2017 • edited

krancour Apr 13, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krancour commented Apr 13, 2017

bacongobbler commented Apr 13, 2017

bacongobbler commented Apr 10, 2017 •

edited

bacongobbler commented Apr 11, 2017 •

edited

bacongobbler commented Apr 12, 2017 •

edited

bacongobbler commented Apr 12, 2017 •

edited

bacongobbler Apr 13, 2017 •

edited

bacongobbler Apr 13, 2017 •

edited

bacongobbler commented Apr 13, 2017 •

edited

krancour Apr 13, 2017 •

edited