From 2181acfdc228403c6a901b904fde10b1e662fec5 Mon Sep 17 00:00:00 2001 From: David Wrede Date: Wed, 8 Jun 2016 13:31:20 -0700 Subject: [PATCH] Initial draft of service group how to docs Signed-off-by: David Wrede Pull request: #672 Approved by: juliandunn --- www/data/docs_sidebar.json | 4 ++ .../docs/run-packages-service-groups.html.md | 43 +++++++++++++++++++ .../getting-started-configure-plan.html.md | 2 +- 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 www/source/docs/run-packages-service-groups.html.md diff --git a/www/data/docs_sidebar.json b/www/data/docs_sidebar.json index 5454b68280..516a96bb83 100644 --- a/www/data/docs_sidebar.json +++ b/www/data/docs_sidebar.json @@ -80,6 +80,10 @@ "title": "Run packages", "link": "/docs/run-packages-overview/", "sub_links": [ + { + "title": "Service groups", + "link": "/docs/run-packages-service-groups/" + }, { "title": "Binding", "link": "/docs/run-packages-binding/" diff --git a/www/source/docs/run-packages-service-groups.html.md b/www/source/docs/run-packages-service-groups.html.md new file mode 100644 index 0000000000..54314711e2 --- /dev/null +++ b/www/source/docs/run-packages-service-groups.html.md @@ -0,0 +1,43 @@ +--- +title: Run packages in a service group +--- + +# Run packages in a service group +A service group is a logical grouping of services with the same package and topology type connected together in a ring. They are created to share configuration and file updates among the services within those groups and can be segmented based on workflow or deployment needs (QA, Production, and so on). Updates can also be [encrypted](/docs/run-packages-security#service-group-encryption) so that only members of a specific service group can decrypt the contents. + +By default, every service joins the `default` service group unless otherwise specified at runtime. + +In addition, multiple service groups can reside in the same ring. This allows data exposed by supervisors to be shared with other members of the ring regardless of which group they are in. + +## Joining a service group +To join a service group, run your service either natively with the `hab start` command, or through an external runtime format such as a Docker container. A best practice is to name the group _servicename_._environment_ to support continuous deployment workflows. + +Here's how to start up the service using the supervisor (`hab-sup`) directly: + + hab start myorigin/myapp --group myapp.prod + +Here's how to run the same command from a Docker container: + + docker run -it myorigin/myapp --group myapp.prod + +You will see a similar output below when your service starts. The census entry shows which service group your service belongs to using the format _servicename_._groupname_. Keep this service instance running. + + hab-sup(MN): Starting myorigin/myapp + hab-sup(GS): Supervisor 172.17.0.2: 38a2ac4f-5348-48df-86f0-b293284740ce + hab-sup(GS): Census myapp.myapp.prod: c60bfa12-c913-4f89-b4f3-d082d1310c3d + ... + +Services only join together to form a ring when a peer IP address is specified by other similar services at runtime. In a new window or external runtime format, run the same command you ran above, but this time, reference the peer IP address of the previous service specified in the supervisor output above. + + hab start myorigin/myapp --group myapp.prod --peer 172.17.0.2 + + The output for this new service shows that it has either formed a new ring with the service above, or joined an existing ring where the other service was a member. Specifying the group name and peer values together ensures that the new service has joined the `myapp.prod` service group. + + hab-sup(MN): Starting myorigin/myapp + hab-sup(GS): Supervisor 172.17.0.3: 426f2b49-fb04-41fa-b656-f43260ab122e + hab-sup(GS): Census myapp.myapp.prod: 1f9412eb-c1df-4df8-a07a-65540333826a + hab-sup(GS): Starting inbound gossip listener + hab-sup(GS): Joining gossip peer at 172.17.0.2:9634 + ... + +> Note: It is important that you specified the group value above. If not, then your new service would have joined the `default` service group, but remained a gossip peer of the previous service. diff --git a/www/source/tutorials/getting-started-configure-plan.html.md b/www/source/tutorials/getting-started-configure-plan.html.md index e6ea6f08cd..1f4f98285a 100644 --- a/www/source/tutorials/getting-started-configure-plan.html.md +++ b/www/source/tutorials/getting-started-configure-plan.html.md @@ -3,7 +3,7 @@ title: Add configuration to your plan --- # Add configuration to your plan -When you create a plan, you may optionally define which configuration settings can be overridden through the use of a templatized [Handlebars.js](https:handlebars.js.com) version of the native application configuration file. Default settings are then specified in and updated from a corresponding [TOML](https://github.com/toml-lang/toml) file. +When you create a plan, you may optionally define which configuration settings can be overridden through the use of a templatized [Handlebars.js](http://handlebarsjs.com) version of the native application configuration file. Default settings are then specified in and updated from a corresponding [TOML](https://github.com/toml-lang/toml) file. In this tutorial, the archive for our Node.js app already has a configuration file called `config.json` that populates a message and specifies a listening port for the http server. We will use that file as a template for the settings that can be overridden at start up or while our service is running.