Hyper Open Edge Cloud

How To Add A Service

How to add a service
  • Last Update:2021-06-02
  • Version:002
  • Language:en

Agenda

  • Add Services
  • Add Graceful Template
  • Download graceful template
  • Render Graceful template
  • Verification

This Tutorial describe how to deploy a new service running in the instance.

HTML5AS instance already has one service running, Nginx the server serving the website. Here we will add a graceful restart service to Nginx so that any change in its configuration is taken into account.

To illustrate this process in html5as we will introduce the following elements:

  • A template to send the signal to Nginx for gracefully restart.
  • Add a new parameter port to dynamically change the listening port for nginx.

Without the graceful service, the change of the listening port in the configuration wouldn't be taken into account until the next hard restart of nginx. This only happens when the server reboot in case of a production environment. The graceful service will exit upon sending the signal to nginx but will be restarted automatically every time the instance is processed by slapos node making sure nginx is running with the latest configuration.

Here is the commit introducing this functionality to html5as Software release: commit diff.

Add Services

  • Services are run by supervisord.
  • Any executable placed in INSTANCE-ROOT/etc/run/ will automatically be considered a service.
  • To add a service to an instance, render its executable in INSTANCE-ROOT/etc/run/

Services that are not running will be started automatically at the end of an instanciation.

Add graceful.in

The process of adding a new template has already be covered in How To Add A Template

HUP Signal is sent to the process by the kill command to request a graceful restart. The pid must be obtained from the pid file used by nginx and defined in the instance profile.

Add a new template file in templates/graceful.in with the following content

#! {{ param_html5as['path_shell'] }}
# BEWARE: This file is operated by slapos node
# BEWARE: It will be overwritten automatically

# Run graceful
exec kill -s SIGHUP $(cat {{ param_html5as['path_pid'] }})

Add graceful in buildout.hash.cfg

In order to track the new file and automatically update its md5sum, it needs to be added to buildout.hash.cfg

[template_graceful]
_update_hash_filename_ = templates/graceful.in
md5sum =

You can refer HowTo Update MD5 Checksum in Theia to get more information.

Download graceful in software.cfg

Update software.cfg to download the template

[template-cfg]
...
context =
....
  key template_graceful_target template_graceful:target

...
[template_graceful]
<= download-base

Edit instance.cfg.in

Edit instance.cfg.in to make the template available to instance_html5as.cfg.in

[profile-common]
...
template_graceful  = {{ template_graceful_target }}

Render Graceful in instance_html5as.cfg.in

Add a new section [nginx-graceful] in instance_html5as.cfg.in to render the template.

mode is 0700 to be an executable. The section param_html5as is passed as context to get the pid file of nginx.

### Nginx Graceful
[nginx-graceful]
recipe = slapos.recipe.template:jinja2
template = {{ parameter_list['template_graceful'] }}
rendered = ${basedirectory:script}/nginx-graceful
mode = 0700
context =
    section param_html5as html5as

Add graceful to processed parts

The new graceful section won't be processed because no other section depend on it. This is why nginx-graceful must be added to the list of parts to be processed by buildout in instance_html5as.cfg.in.

[buildout]
parts =
    ...
    nginx-graceful

Add new parameter: port

Add a new parameter port in [slap-parameter] section of instance_html5as.cfg.in. For backward compatibility the port default to 8081 

[slap-parameter]
...
port = 8081

Use parameter port

Update the configuration of the port key in the [html5as] section of instance_html5as.cfg.in by using ${slap-parameter:port} instead of hard-coded 8081

[html5as]
...
# Network
...
port = ${slap-parameter:port}
...

Update md5sum

Refer How To Move to md5sum automatic update to update md5sum:

$ cd ~/srv/project/slapos/software/html5as-base
$ ../../update-hash

Validation

  1. Request instance with port=8086
  2. Verify Exited Graceful Status
  3. Verify server_url with port=8086

To validate this tutorial, we are supposed to request the instance with port parameter and have graceful exited. 

Request instance with port=8086

Refer How To Add A Parameter to have the instance requested with port parameter:

Add port parameter in request script. Make sure to edit it in your request file instead of the example one :

slapos request $sofware_name'_1' $software_release_uri --parameters ... port=8086

Request:

$ cd ~/srv/project/slapos/software/html5as-base/
$ bash ../../../request-html5as-base.sh 

The instance will be re-instantiated by auto-running. You are supposed to inspect the log of slapos node instance

$ tail -f ~/srv/runner/var/log/slapos-node-instance.log

You can observe that the output of request script is still with 8081 port for server_url, which will be replaced by 8086 as you edited in the request script.

Verify Exited Graceful Status

$ slapos node status
...
slappart0:nginx-graceful         EXITED    Mar 11 11:42 AM
..

nginx-graceful is EXITED as expected.

Verify server_url with port=8086

New server_url connection parameter use port 8086. The link can be curled:

$ curl server_url(using new port)

The same output is expected.