juju-core

Merge lp:~mark-mims/juju-core/docs-interfaces-overview into lp:juju-core/docs

  1. docs-interfaces-overview
  2. Merge into docs
Proposed by Mark Mims
Status: Merged
Approved by: Dave Cheney
Approved revision: no longer in the source branch.
Merged at revision: 94
Proposed branch: lp:~mark-mims/juju-core/docs-interfaces-overview
Merge into: lp:juju-core/docs
Diff against target: 363 lines (+337/-0)
3 files modified
htmldocs/authors-interfaces.html (+335/-0)
htmldocs/navigation.html (+1/-0)
htmldocs/navigation.json (+1/-0)
To merge this branch: bzr merge lp:~mark-mims/juju-core/docs-interfaces-overview
Reviewer Review Type Date Requested Status
Nick Veitch (community) Approve
Dave Cheney (community) lgtm Approve
Review via email: mp+183293@code.launchpad.net

Description of the change

interfaces overview for charm authors

To post a comment you must log in.
Revision history for this message
Dave Cheney (dave-cheney) :
review: Approve (lgtm)
Revision history for this message
Nick Veitch (evilnick) wrote :

+1

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added file 'htmldocs/authors-interfaces.html'
2--- htmldocs/authors-interfaces.html 1970-01-01 00:00:00 +0000
3+++ htmldocs/authors-interfaces.html 2013-08-30 22:21:40 +0000
4@@ -0,0 +1,335 @@
5+<!DOCTYPE html>
6+<html>
7+ <head>
8+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9+ <title>Juju Documentation - Scaling Services</title>
10+ <link href='https://fonts.googleapis.com/css?family=Ubuntu:400,300,300italic,400italic,700,700italic|Ubuntu+Mono' rel='stylesheet' type='text/css' />
11+ <link rel="stylesheet" type="text/css" media="screen" href="//juju.ubuntu.com/wp-content/themes/juju-website/css/reset.css" />
12+ <link rel="stylesheet" type="text/css" media="screen" href="//juju.ubuntu.com/wp-content/themes/juju-website/css/960.css" />
13+ <link rel="stylesheet" type="text/css" media="screen" href="//juju.ubuntu.com/wp-content/themes/juju-website/css/base.css" />
14+ <link rel="stylesheet" type="text/css" media="screen" href="//juju.ubuntu.com/wp-content/themes/juju-website/css/home-new.css" />
15+ <link rel='stylesheet' id='stacktack-css' href='//juju.ubuntu.com/wp-content/plugins/stacktack/css/stacktack.min.css?ver=3.4.2' type='text/css' media='all' />
16+ <link href="css/main.css?1375975745" rel="stylesheet" type="text/css"/>
17+
18+ <!--[if lt IE 9]>
19+ <script type="text/javascript" src="//html5shim.googlecode.com/svn/trunk/html5.js"></script>
20+ <![endif]-->
21+</head>
22+ <body class="resources">
23+ <header class="global clearfix" role="banner">
24+ <div class="header-navigation">
25+ <div>
26+ <nav role="navigation">
27+ <ul>
28+ <li class="page_item page-item-6"><a href="https://juju.ubuntu.com/">Home</a></li>
29+ <li class="page_item page-item-7"><a href="https://juju.ubuntu.com/get-started/">Get started</a></li>
30+ <li class="page_item page-item-9 current_page_item"><a href="https://juju.ubuntu.com/resources/">Resources</a></li>
31+ <li class="page_item page-item-13"><a href="https://juju.ubuntu.com/community/">Community</a></li>
32+ <li class="page_item page-item-3688"><a href="https://juju.ubuntu.com/charm-store/">Charm Store</a></li>
33+ <li class="page_item page-item-3691"><a href="https://juju.ubuntu.com/events/">Events</a></li>
34+ <li class="page_item page-item-4474"><a href="https://juju.ubuntu.com/charm-championship/">Charm Championship</a></li>
35+ <li class="page_item page-item-4249"><a href="https://juju.ubuntu.com/survey/">Survey</a></li>
36+ <li>
37+ <form id="form-search" method="get" action="https://juju.ubuntu.com/">
38+ <fieldset>
39+ <input id="input-search" type="text" name="s" value="Search" />
40+ </fieldset>
41+ </form>
42+ </li>
43+ </ul>
44+ </nav>
45+ </div>
46+ </div>
47+ <div class="header-content">
48+ <div class="clearfix">
49+ <img src="https://juju.ubuntu.com/wp-content/themes/juju-website/img/arrow-nav.png" width="9" height="5" style="left:455px; display: block;" class="arrow-nav">
50+ <div class="header-navigation-secondary"></div>
51+ <div class="header-image"></div>
52+ <h1>Resources</h1>
53+ <h2>A collection of some of the most important online references for Juju users and developers.</h2>
54+ </div>
55+ </div>
56+</header>
57+
58+ <section id="content" class="container-12">
59+ <div class="grid-12 doc-container">
60+ <div id="navlinks" class="grid-3 doc-navigation">LINKS</div>
61+ <div class="grid-9 doc-content">
62+ <article>
63+
64+
65+<!--Actual docs start here-->
66+
67+ <section id="authors-interfaces">
68+ <h1>Interfaces</h1>
69+ <p></p>
70+
71+ <p>
72+ One of the best aspects of juju is how dead-simple it is to write a charm.
73+ You write a handful of hooks in your favorite language and then go to town.
74+ However, there's a subtle hump in the charming learning curve... interfaces.
75+ </p>
76+
77+ <p>
78+ Interface names are what juju checks when trying to determine if two services can be related.
79+ For example, wordpress's <code>metadata.yaml</code> contains:
80+ </p>
81+
82+<pre class="prettyprint">
83+requires:
84+ database:
85+ interface: mysql
86+</pre>
87+
88+ <p>
89+ which is a statement that wordpress has a relation that's locally named "database" which is an
90+ implementation of the "mysql" interface.
91+ </p>
92+
93+ <p>
94+ Mysql's <code>metadata.yaml</code> contains a not-too-surprising:
95+
96+<pre class="prettyprint">
97+provides:
98+ db:
99+ interface: mysql
100+</pre>
101+
102+ <p>
103+ When services are related, Juju decides which hooks to call
104+ within each charm based on this local relation name. When
105+ wordpress is related to mysql, the "database-relation-joined,
106+ database-relation-changed, etc" hooks are called on the wordpress
107+ end. Corresponding hooks will be called on the mysql end
108+ "db-relation-joined, db-relation-changed" (based on the mysql
109+ relation names).
110+ </p>
111+
112+ <p>
113+ Juju decides which services can be related based on the interface names only.
114+ They have to match.
115+ </p>
116+
117+ <p>
118+ At the end of the day, what's a juju interface? Simply a name.
119+ </p>
120+
121+ <p>
122+ Now, having gotten that out of the way, there is an _implicit_ notion of an interface
123+ that charmers have to pay attention to in addition to just matching names.
124+ </p>
125+
126+ <p>
127+ In some sense, relations are two-way channels of communications between services.
128+ They're not actually talking directly, the agents communicate via the state server, but
129+ it helps to think of it as direct communication between the services.
130+ Relation hooks can call tools such as <code>relation-get</code> and <code>relation-set</code>
131+ to pass information back and forth between the service endpoints.
132+ </p>
133+
134+ <p>
135+ For example, wordpress and mysql might have a conversation like the following:
136+ </p>
137+
138+<pre class="prettyprint">
139+wordpress:
140+ I'm here and my service name is "wordpress"
141+
142+mysql:
143+ I'm here, let me create a db for you
144+ your database/schema name is "wordpress"
145+ your credentials are "admin/pass1234"
146+ you access the db on "my.host.addr:port"
147+
148+wordpress:
149+ cool, let me write the wordpress config files needed to access that database (and bounce the server to pick up those changes)
150+ later
151+
152+mysql:
153+ cool, later
154+</pre>
155+
156+ <p>
157+ We'll go over some more detailed versions of this, but this is
158+ the high-level conversation that occurs between two services when
159+ they are related in a relation implementing the
160+ <code>mysql</code> interface.
161+ </p>
162+
163+ <p>
164+ At first glance, it would appear that the <em>interface</em> called <code>mysql</code>
165+ might be defined simply by the set of variables that get passed along the channel.
166+ Something like:
167+ </p>
168+
169+<pre class="prettyprint">
170+interface:
171+ name: mysql
172+ variables_set:
173+ - service_name
174+ - database_host
175+ - database_port
176+ - database_name
177+ - database_user
178+ - database_password
179+</pre>
180+
181+ <p>
182+ but really, that's not complete. In fact, it's not even enough
183+ information to implement hooks for a new service that needs to
184+ talk to mysql. The timing and sequencing are critical
185+ components of this conversation! They can't be left out.
186+ </p>
187+
188+ <p>
189+ So let's dig a little deeper into this interface.
190+ Consider only the <code>relation-joined</code> and <code>relation-changed</code>
191+ hooks for now. The remaining <code>broken</code> and <code>departed</code> hooks are covered
192+ elsewhere.
193+ </p>
194+
195+ <p>
196+ Actually, if we start from provisioning, the hooks that are called for wordpress are
197+ </p>
198+
199+<pre class="prettyprint">
200+# juju deploy wordpress
201+
202+install
203+config-changed
204+start
205+
206+# juju add-relation wordpress mysql
207+
208+database-relation-joined
209+
210+database-relation-changed
211+</pre>
212+
213+
214+ <p>
215+ similarly, for mysql
216+ </p>
217+
218+
219+<pre class="prettyprint">
220+# juju deploy mysql
221+
222+install
223+config-changed
224+start
225+
226+# juju add-relation wordpress mysql
227+
228+db-relation-joined
229+
230+db-relation-changed
231+</pre>
232+
233+
234+ <p>
235+ and we can fill in a little of what the relation hooks are doing
236+ </p>
237+
238+
239+<pre class="prettyprint">
240+# wordpress
241+
242+database-relation-joined
243+ &lt;no-op&gt;
244+
245+database-relation-changed
246+ relation-get database_name, creds, host/port
247+ write config for wordpress
248+ bounce wordpress
249+</pre>
250+
251+<pre class="prettyprint">
252+# mysql
253+
254+db-relation-joined
255+ relation-get service-name
256+ create db, creds
257+ relation-set db, creds, host/port
258+
259+database-relation-changed
260+ &lt;no-op&gt;
261+</pre>
262+
263+ <p>
264+ <em>This</em> conversation is the actual interface.
265+ </p>
266+
267+
268+ </section>
269+
270+ <!--Actual docs end here-->
271+
272+
273+
274+ </article>
275+ </div>
276+ </div>
277+ </section>
278+ <div class="shadow"></div>
279+ <footer class="global clearfix" role="contentinfo">
280+ <div class="row">
281+ <div class="inner-wrapper">
282+ <nav role="navigation" class="clearfix">
283+ <ul class="footer-a">
284+ <li class="grid-3 first-col">
285+ <h4><a href="/get-started">Get started</a></h4>
286+ <ul>
287+ <li class="page_item page-item-20"><a href="https://juju.ubuntu.com/get-started/local/">Local</a></li>
288+ <li class="page_item page-item-22"><a href="https://juju.ubuntu.com/get-started/amazon/">Amazon Web Services</a></li>
289+ <li class="page_item page-item-18"><a href="https://juju.ubuntu.com/get-started/hp-cloud/">HP Cloud</a></li>
290+ <li class="page_item page-item-16"><a href="https://juju.ubuntu.com/get-started/rackspace/">Rackspace</a></li>
291+ <li class="page_item page-item-3596"><a href="https://juju.ubuntu.com/get-started/openstack/">Openstack</a></li>
292+ <li class="page_item page-item-3600"><a href="https://juju.ubuntu.com/get-started/maas/">MAAS</a></li>
293+ </ul>
294+ </li>
295+ <li class="grid-3">
296+ <h4><a href="/resources">Resources</a></h4>
297+ <ul>
298+ <li><a href="http://juju.ubuntu.com/docs">Documentation</a></li>
299+ <li><a href="/resources/videos/">Videos</a></li>
300+ <li><a href="http://uistage.jujucharms.com:8080/">Juju GUI demo site</a></li>
301+ </ul>
302+ </li>
303+ <li class="grid-3">
304+ <h4><a href="/community">Community</a></h4>
305+ <ul>
306+ <li class="page_item page-item-28"><a href="https://juju.ubuntu.com/community/juju-blog/">Juju Blog</a></li>
307+ <li class="page_item page-item-4262"><a href="https://juju.ubuntu.com/community/weekly-charm-meeting/">Weekly Charm Meeting</a></li>
308+ <li class="page_item page-item-4036"><a href="https://juju.ubuntu.com/community/charmers/">Charmers</a></li>
309+ <li><a href="https://lists.ubuntu.com/mailman/listinfo/juju">Mailing List</a></li>
310+ <li><a href="http://webchat.freenode.net/?channels=juju">Chat</a></li>
311+ <li><a href="http://askubuntu.com/questions/tagged/juju?sort=faq&pagesize=50">FAQ</a></li>
312+ </ul>
313+ </li>
314+ <li class="grid-3 last-col">
315+ <h4><a href="https://launchpad.net/juju">Code</a></h4>
316+ <ul>
317+ <li><a href="https://launchpad.net/juju-core">Juju Core</a></li>
318+ <li><a href="https://launchpad.net/charms">Charms</a></li>
319+ </ul>
320+ </li>
321+ </ul>
322+ </nav>
323+ </div>
324+ </div>
325+ <div class="row no-border">
326+ <div class="legal inner-wrapper">
327+ <p>&copy; 2013 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.</p>
328+ <p><a href="https://bugs.launchpad.net/juju-website/+filebug">Report a bug on this site</a></p>
329+ </div>
330+ </div>
331+</footer>
332+
333+ <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
334+ <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.14/jquery-ui.min.js"></script>
335+ <script src="//d38yea5fb4e2oh.cloudfront.net/jquery.stacktack.min.js"></script>
336+ <script type="text/javascript" src="js/main.js"></script>
337+ <script type="text/javascript" src="http://code.jquery.com/jquery-1.9.1.js"></script>
338+ </body>
339+</html>
340
341=== modified file 'htmldocs/navigation.html'
342--- htmldocs/navigation.html 2013-08-30 21:03:26 +0000
343+++ htmldocs/navigation.html 2013-08-30 22:21:40 +0000
344@@ -27,6 +27,7 @@
345 <li class=" sub"><a href="authors-implicit-relations.html">Implicit Relations</a></li>
346 <li class=" sub"><a href="authors-testing.html">Charm Testing</a></li>
347 <li class=" sub"><a href="authors-hooks.html">Hook debugging</a></li>
348+ <li class=" sub"><a href="authors-interfaces.html">Interfaces</a></li>
349 <li class=" sub"><a href="authors-charms-in-action.html">Charms in action!</a></li>
350 <li class=""><a href="authors-charm-store.html">The Juju Charm Store</a></li>
351 <li class=" sub"><a href="authors-charm-policy.html">Charm store policy</a></li>
352
353=== modified file 'htmldocs/navigation.json'
354--- htmldocs/navigation.json 2013-08-30 21:03:26 +0000
355+++ htmldocs/navigation.json 2013-08-30 22:21:40 +0000
356@@ -36,6 +36,7 @@
357 "Implicit Relations": "authors-implicit-relations.html",
358 "Charm Testing": "authors-testing.html",
359 "Hook Debugging": "authors-hooks.html",
360+ "Interfaces": "authors-interfaces.html",
361
362 }
363 },

Subscribers

People subscribed via source and target branches