docs(src/applications/inter-app-communication.md) Add first draft #723
Conversation
chexxor
changed the title
|
This is a good start on something that would be very useful to users. We should refer to "Workflow" or "Deis Workflow" consistently, instead of the old shorthand "Deis." |
|
I've got a lot of PRs in many repos, so this one slipped off my radar. Thanks for the review! |
|
Do we need to do something in mkdocs.yml to surface this new page? I was browsing this repo and came across that file. |
|
Yes indeed, a change to mkdocs.yml to add it to the TOC will be required in order for this page to be available. |
|
I've added the page to the mkdocs.yml. Also, I've added a section to explain a closely related Deis Workflow feature: |
|
LGTM still stands -- good catch on mkdocs addition! |
| For example, if you deployed a Deis Workflow app like this: | ||
|
|
||
| $ deis create http-server --no-remote | ||
| $ deis pull deis/example-dockerfile-python:latest -a http-server |
There was a problem hiding this comment.
example-go is usually the app of choice in the documentation, as the image is 10x smaller than example-dockerfile-python:
><> docker images | grep example
deis/example-dockerfile-python latest 811c39971f48 12 weeks ago 43.5 MB
deis/example-go latest 6d128cdcba34 2 years ago 4.072 MB
There was a problem hiding this comment.
I get a readiness check failure when using deis/example-go.
$ deis pull deis/example-go -a http-server
Creating build... Error: Unknown Error (400): {"detail":"(app::deploy): Readiness probe failed: dial tcp 10.68.7.165:8080: getsockopt: connection refused"}
Same error when pulling "deis/example-dockerfile-python:latest", so I dunno how to fix.
| $ deis create http-client --no-remote | ||
| $ # Need to set a port because the docker image doesn't use one. | ||
| $ deis config:set PORT=8080 -a http-client | ||
| $ deis config:set HOSTNAME=http-server.http-server |
There was a problem hiding this comment.
You can set both of these in one line:
deis config:set PORT=8080 HOSTNAME=http-server.http-server -a http-client
|
|
||
| Clean up: | ||
|
|
||
| $ deis destroy -a http-server --confirm=http-server |
There was a problem hiding this comment.
I don't believe cleanup should be documented. The user following the guide may want to play around with the example some more.
There was a problem hiding this comment.
I disagree. The kubernetes tutorial docs demonstrate cleanup hello-minikube. Also, this command and its comment are pretty clear, so a user wanted to continue playing can simply wait to execute this until they are done playing. Or they can restart from the beginning to start playing again.
| $ # Need to set a port because the docker image doesn't use one. | ||
| $ deis config:set PORT=8080 -a http-client | ||
| $ deis config:set HOSTNAME=http-server.http-server | ||
| $ deis pull -a http-client willfarrell/ping:latest |
There was a problem hiding this comment.
Running deis pull on this image fails because it does not listen on port 8080 and fails the default health check. I don't think it's useful for a demonstration if the app fails to be deployed.
><> deis pull -a http-client willfarrell/ping:latest
Creating build... Error: Unknown Error (400): {"detail":"(app::deploy): Readiness probe failed: dial tcp 172.17.0.26:8080: getsockopt: connection refused"}
There was a problem hiding this comment.
I need a better suggestion if I'm going to change it. I spent a lot of time thinking about how to demonstrate inter-app comms, and this is the best I could find.
There was a problem hiding this comment.
|
|
||
| ### Environment Variable Service Discovery | ||
|
|
||
| It's useful to note that Kubernetes also supports [environment variable service discovery](https://kubernetes.io/docs/user-guide/services/#environment-variables), which works by adding environment variables to an app's environment to provide a reference to other services in the app's namespace. This method is currently not supported by Deis Workflow because Workflow creates a separate namespace for each app it deploys. |
There was a problem hiding this comment.
We shouldn't document this if we don't plan on supporting it. Either this should reference a ticket like deis/controller#710 to make an action item or should be removed completely.
There was a problem hiding this comment.
It's my understanding that Deis wants to follow Heroku's model, and Heroku doesn't support separate namespaces for each. That issue doesn't indicate any desire by core team to support defining a namespace. It's better to document this design decision than make people wonder.
|
|
||
| ### Related Topics | ||
|
|
||
| A common architecture pattern of multi-process applications is to have one process serve public requests while having multiple other processes supporting the public one to, for example, perform actions on a schedule or process work items from a queue. To implement this system of apps in Deis Workflow, set up the apps to communicate using DNS resolution, as shown above, and hide the supporting processes from public view by removing them from the Deis Workflow router. |
There was a problem hiding this comment.
I think this should go up further as a supporting use case for inter-app communication rather than a separate heading.
|
|
||
| A common architecture pattern of multi-process applications is to have one process serve public requests while having multiple other processes supporting the public one to, for example, perform actions on a schedule or process work items from a queue. To implement this system of apps in Deis Workflow, set up the apps to communicate using DNS resolution, as shown above, and hide the supporting processes from public view by removing them from the Deis Workflow router. | ||
|
|
||
| deis routing:disable -a supporting-scheduled-app |
There was a problem hiding this comment.
missing $ character to note this is a console command.
|
|
||
| Deis Workflow supports deploying a single app composed of a system of processes. Each Deis Workflow app communicates on a single port, so communicating with another Workflow app means finding that app's address and port. All Workflow apps are mapped to port 80 externally, so finding its IP address is the only challenge. Workflow creates a [Kubernetes Service](https://kubernetes.io/docs/user-guide/services/) for each app, which effectively assigns a name and one cluster-internal IP address to an app. The DNS service running in the cluster adds and removes DNS records which point from the app name to its IP address as services are added and removed. Deis Workflow apps, then, can simply send requests to the domain name given to the service, which is "app-name.app-namespace". | ||
|
|
||
| For example, if you deployed a Deis Workflow app like this: |
There was a problem hiding this comment.
Overall I think the documentation is going in the right direction, but I don't think the demonstration is useful. Perhaps just remove the demo and leave the last sentence?
The blog post "Private Applications on Workflow" provides more details by walking through an example of internal cluster DNS communication.
There was a problem hiding this comment.
What isn't useful about the demonstration? Can we find a better one?
There was a problem hiding this comment.
The blog post I linked has two working apps that communicate internally using DNS.
There was a problem hiding this comment.
The blog post is nice, but the http client is more complicated than I like. It requires knowledge of nginx, proxy, and authentication. This example only requires knowledge of unix ping, which is more simple, IMO.
Also, a blog post is different than a doc page. Linking to a blog post isn't an acceptable form of docs, IMO. For example, if CLI tool changes, then we can't grep the doc repo to know there's a doc page we need to update.
|
ping @chexxor, will you be able to come back to this, or shall I remove this from the v2.13.0 milestone? |
|
Updated. Thanks for review! |
|
If you wouldn't mind amending your commit(s) such that it follows the commit style guide, that would be awesome! That way it'll get picked up by |
Add first draft of inter-app communication. Apply changes requested by review.
chexxor
force-pushed
the
add-inter-app-comm-docs
branch
from
ab525fa to
8980c62
Compare
|
Thanks for maintaining! |
|
No, thank you. |
Here's a first draft at documenting communication between Deis apps, which would fix https://github.com/deis/workflow/issues/
I spent a lot of time trying to come up with a simple example of an http-client app which resolves an app's URL to its internal IP address. I couldn't find an existing docker image which runs properly on Deis, as I don't have a great understanding of what kind of docker image a Deis app can simply run. I found a "ping" image which successfully demonstrates DNS resolution, but the pings fail when run in Deis.
LMK of any other info which should be contained here. I'll probably take a second review later.