Add documentation about templating support on… #28486

vdemeester · 2016-11-16T17:57:09Z

… services creation/update. It's a rough first attemp 👼

/cc @thaJeztah @mstanleyjones

🐸

Signed-off-by: Vincent Demeester vincent@sbr.pm

mdlinville · 2016-11-16T18:51:36Z

docs/reference/commandline/service_create.md

Do we want to call it "Templating" or maybe something like "Create services using templates"?

mdlinville · 2016-11-16T18:53:25Z

docs/reference/commandline/service_create.md

You can use templates for some flags of service create, using the syntax provided by the text/template package provided by the Go language.

Or something like that.

mdlinville · 2016-11-16T18:53:55Z

docs/reference/commandline/service_create.md

Maybe title this section:

Template example

mdlinville · 2016-11-16T18:54:27Z

docs/reference/commandline/service_create.md

You'll need to wrap the double-backeted content with {% raw %} and {% endraw %}

From the output below, I can't see what the template is doing. Can you come up with an example that is more meaningful / obviously useful? Or explain to me what I am missing?

mdlinville · 2016-11-16T18:57:04Z

docs/reference/commandline/service_update.md

thaJeztah · 2016-11-18T00:34:15Z

ping @vdemeester 😇

vdemeester · 2016-11-18T14:03:58Z

Updated 👼

thaJeztah

Two nits/questions; wondering if we should also refer to https://docs.docker.com/engine/admin/formatting/, also that is for --format (some things may apply?)

thaJeztah · 2016-11-18T14:16:54Z

docs/reference/commandline/service_create.md

This needs quotes around the format "{{.Config.Hostname}}"

thaJeztah · 2016-11-18T14:18:21Z

docs/reference/commandline/service_update.md

do we need ./ here @mstanleyjones ?

… services creation/update. Signed-off-by: Vincent Demeester <vincent@sbr.pm>

thaJeztah

LGTM

but ping @mstanleyjones to check if the {%raw%} are in the correct place 😄

AkihiroSuda · 2016-11-21T05:05:51Z

docs/reference/commandline/service_create.md

+`.Node.ID`        | Node ID
+`.Task.ID`        | Task ID
+`.Task.Name`      | Task name
+`.Task.Slot`      | Task slot


I think we should note that .Task.Slot falls back to node ID for global services
https://github.com/docker/swarmkit/blob/master/template/context.go#L52

Also, probably it would be better to note that multiple tasks can share the single slot number in certain cases
moby/swarmkit#1741

PTAL @aaronlehmann @stevvooe

Also, probably it would be better to note that multiple tasks can share the single slot number in certain cases

I think you're over-valuing the importance of this particular functionality. It is not important for most users and calling it out every makes it look less useful than it is. In this case, the behavior of Task.Slot isn't important, at all.

In addition, the contents of .Task.Slot should largely be treated as opaque. This avoids consumers making assumptions about the contents of a field that may be broken in future versions.

stevvooe · 2016-11-21T23:04:51Z

docs/reference/commandline/service_create.md

+service's name and the node's ID where it sits.
+
+```bash
+$ docker service create --name hosttempl --hostname={% raw %}"{{.Node.ID}}-{{.Service.Name}}"{% endraw %} busybox top


Why does the first example of this feature include {% raw %}? Is that a feature of the local shell?

@stevvooe nah, that's required for the docs.github.io repo so Jekyll does not mess up the " it seams 😓

Jekyll sees anything in {{}} as template, so tries to parse it

ah right it's about {{ 😅

stevvooe · 2016-11-21T23:08:55Z

LGTM

thaJeztah · 2016-11-21T23:50:41Z

{% raw %} looks consistent with some other parts, let's merge

mostolog · 2017-01-10T08:51:08Z

Already merged #27857 and documented here, but I'm wondering why in https://github.com/docker/docker/blob/master/docs/reference/commandline/service_create.md#create-services-using-templates example:

--name hosttempl --hostname={% raw %}"{{.Node.ID}}-{{.Service.Name}}"{% endraw %}

becomes:

hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj

where those "." came from?

IMHO, example it's not clear enough...

thaJeztah · 2017-01-10T10:26:12Z

@mostolog the {% raw %} and {% endraw %} are not part of the actual example, but unfortunately needed for the tooling that's used to generate the online documentation 😞. The Markdown files in the docs directory are used as source for the online documentation, and may not always be properly formatted for reading on GitHub directly.

thaJeztah · 2017-01-10T10:46:02Z

@mostolog oh, wait; hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj is the name of the task, not its hostname.

mostolog · 2017-01-10T10:59:23Z

@thaJeztah thanks. I was totally confused and ended expecting "node.id" magically transformed to "task.slot"

approxit · 2017-01-25T18:11:57Z

Is there any way to make service hostname inherit it's node hostname?
Would ❤️ to use {{ .Node.Hostname }}.

stevvooe · 2017-01-25T19:39:15Z

The template variables are defined in https://github.com/docker/swarmkit/blob/master/template/context.go#L13. I'd recommend submitting a request over in https://github.com/docker/swarmkit, detailing the use case and how it would be expected to behave.

gr4per · 2017-03-20T10:53:57Z

+1 for this

GordonTheTurtle added the status/0-triage label Nov 16, 2016

vdemeester added process/cherry-pick status/3-docs-review and removed status/0-triage labels Nov 16, 2016

vdemeester added this to the 1.13.0 milestone Nov 16, 2016

mdlinville suggested changes Nov 16, 2016

View reviewed changes

vdemeester force-pushed the docs-service-templating branch from 760dc84 to e74d241 Compare November 18, 2016 14:03

thaJeztah reviewed Nov 18, 2016

View reviewed changes

Add documentation about templating support on…

4571ad0

… services creation/update. Signed-off-by: Vincent Demeester <vincent@sbr.pm>

vdemeester force-pushed the docs-service-templating branch from e74d241 to 4571ad0 Compare November 18, 2016 14:28

thaJeztah approved these changes Nov 18, 2016

View reviewed changes

AkihiroSuda reviewed Nov 21, 2016

View reviewed changes

stevvooe reviewed Nov 21, 2016

View reviewed changes

thaJeztah merged commit 700f618 into moby:master Nov 21, 2016

vdemeester deleted the docs-service-templating branch November 22, 2016 00:09

vieux added process/cherry-picked and removed process/cherry-pick labels Nov 22, 2016

vieux mentioned this pull request Nov 22, 2016

1.13.0-rc2 cherry-picks : part 3 #28674

Merged

vdemeester mentioned this pull request Nov 22, 2016

document templating features in swarm mode #28022

Closed

This was referenced Nov 26, 2016

Adding the hostname option to docker service command #27857

Merged

Fix validation when templating is used on Tasks moby/swarmkit#1738

Merged

billryan mentioned this pull request Jan 9, 2017

--network-alias option missing on docker service create (as well as corresponding options on docker service update) #24787

Closed

approxit mentioned this pull request Feb 14, 2017

[Proposal] docker service create template support for {{ .Node.Hostname }} moby/swarmkit#1951

Closed

Add documentation about templating support on… #28486

Add documentation about templating support on… #28486

Uh oh!

Conversation

vdemeester commented Nov 16, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Template example

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Nov 18, 2016

Uh oh!

vdemeester commented Nov 18, 2016

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah Nov 21, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevvooe commented Nov 21, 2016

Uh oh!

thaJeztah commented Nov 21, 2016

Uh oh!

mostolog commented Jan 10, 2017

Uh oh!

thaJeztah commented Jan 10, 2017

Uh oh!

thaJeztah commented Jan 10, 2017

Uh oh!

mostolog commented Jan 10, 2017

Uh oh!

approxit commented Jan 25, 2017

Uh oh!

stevvooe commented Jan 25, 2017

Uh oh!

gr4per commented Mar 20, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

thaJeztah Nov 21, 2016 •

edited

Loading