TemplateAPI.md in consul-templaterb-1.0.9 vs TemplateAPI.md in consul-templaterb-1.0.10
- old
+ new
@@ -12,29 +12,137 @@
thus the application will display a warning if the template is invalid and won't stop
(`--hot-reload=die` is the default, thus if the hot-reloaded template has issue, the application will die).
Have a look to [samples/](samples/) directory to start writing your own templates.
+## Common structure of returned objects
+
+All objects returned by those functions described below all share the same structure:
+
+* `.result` : handle the result
+* `.endpoint` : get technical information about how data was retrieved and statistics
+
+## Common re-implemented functions for all objects
+
+Most objects returned by all those functions are contained within a `.result` object. However, in order
+to avoid having to write .result in all templates, some shortcuts have been added:
+* `[]` allow to either access values for map-based data or arrays
+* for all objects: `.each`, `sort`, `.select`, `.each_value`, `.count`, `.empty?`
+* additionnaly, for map based results, the following methods are available: `.keys`, `.values`, `.each_pair`,
+ `.each_value`
+
+See [lib/consul/async/consul_template.rb:230](lib/consul/async/consul_template.rb#L230) and
+[lib/consul/async/consul_template.rb:260](lib/consul/async/consul_template.rb#L260) for up to date list of
+all those methods.
+
## datacenters()
[Get the list of datacenters as string array](https://www.consul.io/api/catalog.html#list-datacenters).
+<details><summary>Examples</summary>
+<div class="samples">
+
+### List all datacenters in a text list and count services and nodes within
+
+```erb
+<% datacenters.each do |dc| %>
+ * <%= dc %> with <%= services(dc:dc).keys.count %> services, <%= nodes(dc:dc).count %> nodes
+<% end %>
+```
+
+Full example: [samples/consul_template.txt.erb](samples/consul_template.txt.erb)
+
+</div>
+</details>
+
## services([dc: datacenter], [tag: tagToFilterWith])
[List the services matching the optional tag filter](https://www.consul.io/api/catalog.html#list-services),
if tag is not specified, will match all the services. Note that this endpoint performs client side tag
filtering for services to ease templates development since this feature is not available on Consul's endpoint.
+<details><summary>Examples</summary>
+<div class="samples">
+
+### List all services in default datacenter and display its tags
+
+```erb
+<% services.each do |service_name, tags|
+ %> * <%= service_name %> [ <%= tags %> ]
+<% end %>
+```
+
+Full example: [samples/consul_template.txt.erb](samples/consul_template.txt.erb)
+
+### List all services in all datacenters having tag `http`
+
+```erb
+<%
+ datacenters.each do |dc| %>
+ * Datacenter <%= dc %>
+ <%
+ services(dc:dc, tag:'http').each do |service_name, tags|
+ %>
+ - service <%= service_name %> <%= tags.sort %><%
+ end
+ end
+%>
+```
+
+</div>
+</details>
+
## service(serviceName, [dc: datacenter], [tag: tagToFilterWith], [passing: true])
[List the instances](https://www.consul.io/api/health.html#list-nodes-for-service) of a service having the given
optional tag. If no tag is specified, will return all instances of service. By default, it will return all the
well services that are passing or not. An optional argument passing might be used to retrieve only passing instances.
+<details><summary>Examples</summary>
+<div class="samples">
+
+### List all services instances with http tag on current DC, instances sorted by node name
+
+```erb
+<% services.each do |service_name, tags|
+ if tags.include? 'http'
+%> ++ Service <%= service_name %>
+<% service(service_name, tag:'http').sort {|a,b| a['Node']['Node'] <=> b['Node']['Node'] }.each do |snode|
+%> * <%= service_name %> -> <%=
+ snode['Node']['Node'] %>:<%= snode['Service']['Port'] %> <%=
+ snode['Service']['Tags'] %> status: <%
+ snode['Checks'].each do |c| %> <%= c['Status']
+ %><% end if snode['Checks'] %>
+<% end
+ end
+ end %>
+```
+
+Full example: [samples/consul_template.txt.erb](samples/consul_template.txt.erb)
+
+</div>
+</details>
+
## nodes([dc: datacenter])
[List all the nodes of selected datacenter](https://www.consul.io/api/catalog.html#list-nodes). No filtering is
applied.
+
+<details><summary>Examples</summary>
+<div class="samples">
+
+### List all nodes for DC, sorted by name
+
+```erb
+<% nodes.sort {|a,b| a['Node'] <=> b['Node'] }.each do |snode|
+%> * <%= snode['Address'].ljust(16) %> <%= snode['Node'] %>
+<% end %>
+```
+
+Full example: [samples/consul_template.txt.erb](samples/consul_template.txt.erb)
+
+</div>
+</details>
## node(nodeNameOrId, [dc: datacenter])
[List all the services of a given Node](https://www.consul.io/api/catalog.html#list-services-for-node) using its
name or its ID. If DC is specified, will lookup for given node in another datacenter.