Difference between revisions of "Services/FirstDeployment"

From Wikitech-static
Jump to navigation Jump to search
imported>Dzahn
m (replace tin with deploy1001)
imported>Martyav
Line 1: Line 1:
This page describes how to deploy your first service. It does '''''not''''' cover how to sign up for an account, write code, engage in ongoing projects, or what to do after you've deployed your service.
For what you need to do to join us in deploying services, see [[Help:Getting Started]].
For information on coding new Mediawiki extensions, see [[mw: Review queue]].
For how to deploy to ongoing projects, see [[Services/Deployment]] and [[How to deploy code]].
For help with your service once it's been deployed, see [[How to perform security fixes]] and [[SWAT deploys]]
== Repositories ==
== Repositories ==


We require that all services are hosted on our [[mw:Gerrit|Gerrit servers]]. It does not have to be your primary development technique or tool, even though you are strongly encouraged to do so.
When deploying a new service, two repositories are necessary, because any Node.js services included with the source need to be pre-built for production.
 
First, you need a ''source'' repository, containing the source code for your service.
 
Second, you need a ''deploy'' repository, which will mirror the code actually deployed in production.  


Because Node.js services use npm dependencies which can be binary, these need to be pre-built. Therefore, two repositories are needed; one for the source code of your service, and the other, so-called ''deploy'' repository. Both should be available as WM's Gerrit repositories with the paths ''mediawiki/services/your-service-name'' and ''mediawiki/services/your-service-name/deploy'', respectively. When [[mw:Git/New_repositories/Requests|requesting them]] ask for the former to be a clone of [https://github.com/wikimedia/service-template-node the service template] (or of your own service repository) and the latter to be empty.
{{warning|It is very important that the deploy repository mirrors the code deployed in production at all times.}}


It is important to note that the deploy repository is only to be updated directly before (re-)deploying the service, and not on each patch merge entering the ''master'' branch of the regular repository. In other words, '''the deploy repository mirrors the code deployed in production at all times'''.
The deploy repository must ''only'' to be updated directly before deploying or re-deploying the service. Do not update it every time you merge a patch to the master branch of the source repository.


The remainder of this guide assumes these two repositories have been created and that you have cloned them using your Gerrit account, i.e. not anonymously, with the following outline:
All services are required to be hosted on our [[mw:Gerrit|Gerrit servers]]. Gerrit does not have to be your primary development technique or tool, though we strongly encourage its use. 
 
When [[mw:Git/New_repositories/Requests|requesting the repositories for your service]], ask for the source repository to be a clone of [https://github.com/wikimedia/service-template-node the service template], or of your own service repository. Ask for the deploy repository to be empty.
 
The source repository should have the path, <code>mediawiki/services/your-service-name</code>, and the deploy repository should have the path, <code>mediawiki/services/your-service-name/deploy</code>.
 
The remainder of this guide assumes that the two repositories have been created, and that you have cloned them using your Gerrit account, i.e. not anonymously, with the following outline:


<pre>
<pre>
Line 15: Line 35:
</pre>
</pre>


This guide refers to these two repositories as the ''source repository'' and the ''deploy repository'', respectively.
== Source repo configuration ==
 
If you opt to use our service template for the source repository, it includes a script which automatically updates the deploy repository.  


== Source Repo Configuration ==
However, this script needs to be configured before it will work.


The service template includes an automation script which updates the deploy repository, but it needs to be configured properly in order to work.
=== Package.json ===


=== package.json ===
First, you need to update the source repository's <code>package.json</code> file. Find the <code>deploy</code> field inside of this file. It contains three interesting properties, the most important of which is <code>dependencies</code>.


The first part of the configuration involves keeping your source repository's <tt>package.json</tt> updated. Look for its <tt>deploy</tt> stanza. Depending on the exact machine on which your service will be deployed, you may need to set target to either <code>ubuntu</code> or <code>debian</code> (most likely and default value if missing).
==== Dependencies property ====


If you want to specify a version of Node.JS, different from the official distribution package, set the value of the <tt>node</tt> stanza to the desired version, following [https://github.com/creationix/nvm nvm] versions naming. To explicitly force official distribution package, <code>"system"</code> version can be used.
The <code>dependencies</code> property of the <code>deploy</code> field must be kept up to date at all times.


The important thing is keeping the <tt>dependencies</tt> field up to date at all times. There you should list all of the extra packages that are needed in order to build the npm module dependencies. The <tt>_all</tt> field denotes packages which should be installed regardless of the target distribution, but you can add other, distribution-specific package lists, e.g.:
Whenever you need to install extra packages into your development environment to satisfy node module dependencies, make sure to add them to the <code>dependencies</code> property. This will ensure that the deploy repository can successfully build and update.
 
The <code>_all</code> field of the <code>dependencies</code> property denotes packages which should be installed regardless of the target distribution. You can also add other, distribution-specific package lists, e.g.:


<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
Line 41: Line 65:
</syntaxhighlight>
</syntaxhighlight>


In this example, with the current configuration, packages ''pkg1, pkg2, pkgOne'' and ''pkgTwo'' are going to be installed before building the dependencies. If, instead, the target is changed to <code>debian</code>, then ''pkgA, pkgB, pkgOne'' and ''pkgTwo'' are selected.
In this example, packages ''pkg1, pkg2, pkgOne'' and ''pkgTwo'' are going to be installed before building the list of dependencies. If, instead, the target is changed to <code>debian</code>, then ''pkgA, pkgB, pkgOne'' and ''pkgTwo'' are selected.


As a rule of thumb, '''whenever you need to install extra packages into your development environment for satisfying node module dependencies, add them to deploy.dependencies to ensure the successful build and update of the deploy repository'''.
==== Other properties ====


=== Local Git ===
Depending on the machine that your service will be deployed on, you may need to set the <code>target</code> property of the <code>deploy</code> field, to indicate the expected distribution&ndash;most likely, <code>ubuntu</code> or <code>debian</code>.


The script needs to know where to find your local copy of the deploy repository. To that end, when in your source repository, run:
To specify a version of Node.JS different from the official distribution package, set the value of the <code>node</code> property. Follow the [https://github.com/creationix/nvm nvm] version naming scheme. To explicitly use the official distribution package, set the value of <code>node</code> to <code>system</code>.


<syntaxhighlight lang="shell-session">
=== Local git repository ===
$ git config deploy.dir /absolute/path/to/deploy/repo
 
</syntaxhighlight>
You also need to tell the he script where to find the local copy of the deploy repository. This requires you to set the path within git.


Using the aforementioned local outline, you would type:
To set the path to the local deploy repo, go into your local source repository, and run the following command:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ git config deploy.dir /home/YOU/code/deploy
$ git config deploy.dir /absolute/path/to/deploy/repo
</syntaxhighlight>
</syntaxhighlight>


== Deploy Repo Set-up ==
== Deploy repo set-up ==


If you haven't yet done so, initialise the deploy repository:
If you haven't done so already, initialise the deploy repository:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 74: Line 98:
</syntaxhighlight>
</syntaxhighlight>


Next, you need prepare the deploy repository for usage with [https://doc.wikimedia.org/mw-tools-scap/ Scap3]. Create the <tt>scap</tt> directory inside your deploy repository and fill the contents of <tt>scap/scap.cfg</tt> with:
Next, prepare the deploy repository for our deployment script, [https://doc.wikimedia.org/mw-tools-scap/ Scap3]. Create a <code>scap</code> directory inside your deploy repository, and make a file named <code>scap.cfg</code>. The  <code>scap.cfg</code> file should contain the following:


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
Line 99: Line 123:
</syntaxhighlight>
</syntaxhighlight>


This represents the basic configuration needed by Scap3 to deploy the service. We still need to tell Scap3 on which nodes to deploy and which checks to perform after the deployment on each of the nodes. First, the list of nodes. One file needs to be created: <tt>scap/target-canary, where</tt> you need to put the FQDN of the node that will act as the canary deployment node, i.e. the node that will first receive the new codeFor example, if your target nodes are in the SCB cluster, this file should look like this:
This is the basic configuration needed by Scap3 to deploy the service. We still need to tell Scap3 which nodes to deploy on, and which checks to perform after deployment on each node.
 
=== Listing nodes ===
 
Create a new file in the <code>scap</code> directory, named <code>target-canary</code>. This is where you need to put the fully qualified domain name, or FQDN, of the node that will act as the canary deployment node. This is the node that will receive any new code first.
 
For example, if your target nodes are in the [[mw:SCB cluster|SCB cluster]], the file should look like this:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 107: Line 137:
</syntaxhighlight>
</syntaxhighlight>


The complete list of all targets should be ops-controlled and derives from puppet and conftool. Ask ops to set it up before you do your first production deploy. In the same vein, you need to create the <tt>scap/betacluster-targets</tt> file which will contain the FQDNs of the targets in BetaCluster.
The complete list of all targets should be ops-controlled and derives from [[Puppet]] and [[conftool]]. Ask ops to set it up before you do your first production deploy.  
 
In the same vein, you need to create a <code>scap/betacluster-targets</code> file, which will contain the FQDNs of the targets in [[mw:Beta Cluster|Beta Cluster]]. Beta Cluster is a production-like environment for testing new code.
 
=== Enabling the checker script ===


Finally, enable the automatic checker script to check the service after each deployment by placing the following in <tt>scap/checks.yaml</tt>:
Finally, create a file for the automatic checker script to run after each deployment. Place it in the <code>scap</code> directory, and name it <code>checks.yaml</code>.


<syntaxhighlight lang="yaml">
<syntaxhighlight lang="yaml">
Line 127: Line 161:
</syntaxhighlight>
</syntaxhighlight>


Commit your changes, send them to Gerrit for review and merge them.
Commit your changes locally, create a pull request  on Gerrit for review, and merge them.
 
=== Docker ===
 
The deployment process includes a script that builds the deployment repository using [https://www.docker.com Docker containers], so make sure you have the latest version installed.  


The deployment process includes a script that builds the deployment repository using [https://www.docker.com Docker containers], so make sure you have the latest version installed. Additionally, you need to add your user to the `docker` group after installation so that you don't need to use `sudo` when running the build script:
Additionally, you need to add your user to the `docker` group after installation. This is so that you don't need to use `sudo` when running the build script:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 135: Line 173:
</syntaxhighlight>
</syntaxhighlight>


You need to log out of all of the terminals in order for the change to take effect.
You will need to log out of all terminals in order for the change to take effect.
 
== New service request ==


== New Service Request ==
Before your service can go live, operations needs to take care of a few more things: machine allocation, IPs, LVS, etc.


There are various prerequisites that need to be taken care of on the operational side before your service can see the day of light in production: machine allocation, IPs, LVS, etc. In order to express the intent of deployment, you need to complete a new service request, by filing a task against the [https://phabricator.wikimedia.org/project/profile/1305/ service-deployment-requests project in Phabricator]. Be prepared to give the following information:
To request help from the operations team, file a ticket in the [https://phabricator.wikimedia.org/project/profile/1305/ service-deployment-requests project in Phabricator].  


* ''name'': the name of the service to be deployed
The ticket should contain the following information:
* ''description'': a paragraph explaining clearly what the service does and why it is needed
* ''timeline'': the desired deployment timeline; note that you should allow a minimum of at least two to three weeks cadence
* ''point person'': the person responsible for the service; this is the person that will get called when there are problems with the service when running in production
* ''technologies'': additional information about the service itself, including, but not limited to, the language used for development and any frameworks used
* ''request flow diagram'': a link to a request flow diagram that explains the interaction between your service and any other parts of the operational stack inside the production cluster, such as requests made to MediaWiki, RESTBase, etc.


For some example tickets see {{phabricator|T105538}}, {{phabricator|T117560}}, {{phabricator|T128463}}.
* '''Name''' - the name of the service you wish to deploy
* '''Description''' - a paragraph clearly explaining what the service does, and why it is needed
* '''Timeline''' - the desired deployment timeline; note that you should allow a minimum of at least two to three weeks
* '''Point person''' - the person responsible for the service; this is the person that will get called when there are problems with the service while it is running in production
* '''Technologies''' - additional information about the service itself, including, but not limited to, the language used for development and any frameworks used
* '''Request flow diagram''' - a link to a diagram that explains the interaction between your service and any other parts of the operational stack inside the production cluster, such as requests made to MediaWiki, RESTBase, etc.


== Role and Profile Creation ==
=== Example requests ===


While you are waiting for the service request to be completed, do not fear: you still have useful things to do. You may start by creating your service's Puppet role and profile in the <tt>operations/puppet</tt> repository. First, add your service's deploy repository to the list of repositories deployed in production by appending the following block to <tt>hieradata/common/role/deployment.yaml</tt> (note the extra spaces at the beginning of each line):
See {{phabricator|T105538}}, {{phabricator|T117560}}, and {{phabricator|T128463}} for good examples of successful new service requests.
 
== Role and profile creation ==
 
While you are waiting for the service request to be completed, do not fear: you still have useful things to do. You may start by creating your service's Puppet role and profile in the <code>operations/puppet</code> repository.  
 
First, add your service's deploy repository to the list of repositories deployed in production, by appending the following block to <code>hieradata/common/role/deployment.yaml</code> (note the extra spaces at the beginning of each line):


<syntaxhighlight lang="yaml">
<syntaxhighlight lang="yaml">
Line 160: Line 206:
</syntaxhighlight>
</syntaxhighlight>


Next, create <tt>modules/profile/manifests/<service-name>.pp</tt> and put the following content in it:
Next, create <code>modules/profile/manifests/<service-name>.pp</code>; it should contain the following:


<syntaxhighlight lang="puppet">
<syntaxhighlight lang="puppet">
Line 194: Line 240:
</syntaxhighlight>
</syntaxhighlight>


Note that only configuration specific to your service should be listed here and not the whole configuration file, i.e. only the configuration parameters that your service code accesses via <code>app.conf.*</code>. Instead of in-lining it directly in the module, you can also store the configuration in form of an ERB YAML template in <tt>modules/<service-name>/templates/config.yaml.erb</tt>. Then, simply use it directly for the <tt>config</tt> parameter for the <tt>service::node</tt> resource like so:
Note that only configuration specific to your service should be listed here, and not the whole configuration file, i.e. only the configuration parameters that your service code accesses via <code>app.conf.*</code>.  
 
Instead of in-lining it directly in the module, you can also store the configuration in the form of an [[w:ERB|ERB]] YAML template, in <code>modules/<service-name>/templates/config.yaml.erb</code>. Then, simply use it directly as the <code>config</code> parameter for the <code>service::node</code> resource like so:


<syntaxhighlight lang="puppet">
<syntaxhighlight lang="puppet">
Line 200: Line 248:
</syntaxhighlight>
</syntaxhighlight>


You will also need a role for your service. Put the following code fragment into <tt>manifests/role/<service-name>.pp</tt>:
You will also need a role for your service. Put the following code fragment in <code>manifests/role/<service-name>.pp</code>:


<syntaxhighlight lang="puppet">
<syntaxhighlight lang="puppet">
Line 214: Line 262:
</syntaxhighlight>
</syntaxhighlight>


and add the values for the hiera lookups in place inside <code>hieradata/role/common/<service-name>.yaml</code> as follows:<syntaxhighlight lang="yaml">
and add the values for the [[Puppet Hiera|hiera]] lookups in place inside <code>hieradata/role/common/<service-name>.yaml</code> as follows:<syntaxhighlight lang="yaml">
profile::<service-name>::param_name1: "some-value"
profile::<service-name>::param_name1: "some-value"
profile::<service-name>::param_name2: "some-other-value"
profile::<service-name>::param_name2: "some-other-value"
Line 222: Line 270:
You can now submit the patch for review. Don't forget to mention the service request bug in your commit message.
You can now submit the patch for review. Don't forget to mention the service request bug in your commit message.


== Access Rights ==
== Access rights ==


As the service owner and maintainer, you need to be able to log onto the nodes where your service is running. Once the exact list of target nodes is known, you need to file an [https://phabricator.wikimedia.org/maniphest/task/edit/form/8/ access request ticket] with the following information:
As the service owner and maintainer, you need to be able to log onto the nodes where your service is running. Once the exact list of target nodes is known, you need to file an [https://phabricator.wikimedia.org/maniphest/task/edit/form/8/ access request ticket] with the following information:


* ''Ttile'': Access Request for <list-of-maintainers> for <service-name>
* '''Ttile''' - access Request for <list-of-maintainers> for <service-name>
* ''Description'': <list-of-maintainers> needs access to <list-of-nodes> for operating <service-name>. We need to be able to read the logs at <tt>/srv/log/<service-name></tt> and be able to start/stop/restart it. The task asking for the service's deployment is {<service-request-task-number>}
* '''Description''' - <list-of-maintainers> needs access to <list-of-nodes> for operating <service-name>. We need to be able to read the logs at <tt>/srv/log/<service-name></tt> and be able to start/stop/restart it. The task asking for the service's deployment is {<service-request-task-number>}


This request implies <tt>sudo</tt> rights on the target nodes, so you will need the approval from your manager on the task.
This request implies <code>sudo</code> rights on the target nodes, so you will need the approval from your manager on this task.


[[Category:Services| ]]
[[Category:Services]]
[[Category:Deployment]]
[[Category:Deployment]]
[[Category:How-To]]

Revision as of 19:41, 2 June 2019

This page describes how to deploy your first service. It does not cover how to sign up for an account, write code, engage in ongoing projects, or what to do after you've deployed your service.

For what you need to do to join us in deploying services, see Help:Getting Started.

For information on coding new Mediawiki extensions, see mw: Review queue.

For how to deploy to ongoing projects, see Services/Deployment and How to deploy code.

For help with your service once it's been deployed, see How to perform security fixes and SWAT deploys

Repositories

When deploying a new service, two repositories are necessary, because any Node.js services included with the source need to be pre-built for production.

First, you need a source repository, containing the source code for your service.

Second, you need a deploy repository, which will mirror the code actually deployed in production.

The deploy repository must only to be updated directly before deploying or re-deploying the service. Do not update it every time you merge a patch to the master branch of the source repository.

All services are required to be hosted on our Gerrit servers. Gerrit does not have to be your primary development technique or tool, though we strongly encourage its use.

When requesting the repositories for your service, ask for the source repository to be a clone of the service template, or of your own service repository. Ask for the deploy repository to be empty.

The source repository should have the path, mediawiki/services/your-service-name, and the deploy repository should have the path, mediawiki/services/your-service-name/deploy.

The remainder of this guide assumes that the two repositories have been created, and that you have cloned them using your Gerrit account, i.e. not anonymously, with the following outline:

~/code/
  |- your-service
  -- deploy

Source repo configuration

If you opt to use our service template for the source repository, it includes a script which automatically updates the deploy repository.

However, this script needs to be configured before it will work.

Package.json

First, you need to update the source repository's package.json file. Find the deploy field inside of this file. It contains three interesting properties, the most important of which is dependencies.

Dependencies property

The dependencies property of the deploy field must be kept up to date at all times.

Whenever you need to install extra packages into your development environment to satisfy node module dependencies, make sure to add them to the dependencies property. This will ensure that the deploy repository can successfully build and update.

The _all field of the dependencies property denotes packages which should be installed regardless of the target distribution. You can also add other, distribution-specific package lists, e.g.:

"deploy": {
  "target": "ubuntu",
  "node": "system",
  "dependencies": {
    "ubuntu": ["pkg1", "pkg2"],
    "debian": ["pkgA", "pkgB"],
    "_all": ["pkgOne", "pkgTwo"]
  }
}

In this example, packages pkg1, pkg2, pkgOne and pkgTwo are going to be installed before building the list of dependencies. If, instead, the target is changed to debian, then pkgA, pkgB, pkgOne and pkgTwo are selected.

Other properties

Depending on the machine that your service will be deployed on, you may need to set the target property of the deploy field, to indicate the expected distribution–most likely, ubuntu or debian.

To specify a version of Node.JS different from the official distribution package, set the value of the node property. Follow the nvm version naming scheme. To explicitly use the official distribution package, set the value of node to system.

Local git repository

You also need to tell the he script where to find the local copy of the deploy repository. This requires you to set the path within git.

To set the path to the local deploy repo, go into your local source repository, and run the following command:

$ git config deploy.dir /absolute/path/to/deploy/repo

Deploy repo set-up

If you haven't done so already, initialise the deploy repository:

$ cd ~/code/deploy
$ git review -s
$ touch README.md
$ git add README.md
$ git commit -m "Initial commit"
$ git push -u origin master  # or git review -R if this fails
# go to Gerrit and +2 your change, if needed and then:
$ git pull

Next, prepare the deploy repository for our deployment script, Scap3. Create a scap directory inside your deploy repository, and make a file named scap.cfg. The scap.cfg file should contain the following:

[global]
git_repo: <service-name>/deploy
git_deploy_dir: /srv/deployment
git_repo_user: deploy-service
ssh_user: deploy-service
server_groups: canary, default
canary_dsh_targets: target-canary
dsh_targets: targets
git_submodules: True
service_name: <service-name>
service_port: <service-port>
lock_file: /tmp/scap.<service-name>.lock

[wmnet]
git_server: deploy1001.eqiad.wmnet

[deployment-prep.eqiad.wmflabs]
git_server: deployment-tin.deployment-prep.eqiad.wmflabs
server_groups: default
dsh_targets: betacluster-targets

This is the basic configuration needed by Scap3 to deploy the service. We still need to tell Scap3 which nodes to deploy on, and which checks to perform after deployment on each node.

Listing nodes

Create a new file in the scap directory, named target-canary. This is where you need to put the fully qualified domain name, or FQDN, of the node that will act as the canary deployment node. This is the node that will receive any new code first.

For example, if your target nodes are in the SCB cluster, the file should look like this:

$ cat target-canary 
scb1002.codfw.wmnet

The complete list of all targets should be ops-controlled and derives from Puppet and conftool. Ask ops to set it up before you do your first production deploy.

In the same vein, you need to create a scap/betacluster-targets file, which will contain the FQDNs of the targets in Beta Cluster. Beta Cluster is a production-like environment for testing new code.

Enabling the checker script

Finally, create a file for the automatic checker script to run after each deployment. Place it in the scap directory, and name it checks.yaml.

checks:
  depool:
    type: command
    stage: promote
    command: depool-<service-name>
  endpoints:
    type: nrpe
    stage: restart_service
    command: check_endpoints_<service-name>
  repool:
    type: command
    stage: restart_service
    command: pool-<service-name>

Commit your changes locally, create a pull request on Gerrit for review, and merge them.

Docker

The deployment process includes a script that builds the deployment repository using Docker containers, so make sure you have the latest version installed.

Additionally, you need to add your user to the `docker` group after installation. This is so that you don't need to use `sudo` when running the build script:

$ sudo usermod -a -G docker <your-user>

You will need to log out of all terminals in order for the change to take effect.

New service request

Before your service can go live, operations needs to take care of a few more things: machine allocation, IPs, LVS, etc.

To request help from the operations team, file a ticket in the service-deployment-requests project in Phabricator.

The ticket should contain the following information:

  • Name - the name of the service you wish to deploy
  • Description - a paragraph clearly explaining what the service does, and why it is needed
  • Timeline - the desired deployment timeline; note that you should allow a minimum of at least two to three weeks
  • Point person - the person responsible for the service; this is the person that will get called when there are problems with the service while it is running in production
  • Technologies - additional information about the service itself, including, but not limited to, the language used for development and any frameworks used
  • Request flow diagram - a link to a diagram that explains the interaction between your service and any other parts of the operational stack inside the production cluster, such as requests made to MediaWiki, RESTBase, etc.

Example requests

See task T105538, task T117560, and task T128463 for good examples of successful new service requests.

Role and profile creation

While you are waiting for the service request to be completed, do not fear: you still have useful things to do. You may start by creating your service's Puppet role and profile in the operations/puppet repository.

First, add your service's deploy repository to the list of repositories deployed in production, by appending the following block to hieradata/common/role/deployment.yaml (note the extra spaces at the beginning of each line):

  <service-name>/deploy:
    upstream: https://gerrit.wikimedia.org/r/mediawiki/services/<service-name>/deploy
    checkout_submodules: true

Next, create modules/profile/manifests/<service-name>.pp; it should contain the following:

# == Class: profile::<service-name>
#
# Describe the service here ...
#
# === Parameters
#
# [*param_name1*]
#   Description of param_name1
#
# [*param_name2*]
#   Description of param_name2
#
class profile::<service-name>(
    $param_name1 = hiera('profile::<service-name>::param_name1'),
    $param_name2 = hiera('profile::<service-name>::param_name2,
) {

    service::node { '<service-name>':
        port            => <service-port>,
        config          => {
            param_name1 => $param_name1,
            param_name2 => $param_name2,
        },
        healthcheck_url => '',
        has_spec        => true,
        deployment      => 'scap3',
    }

}

Note that only configuration specific to your service should be listed here, and not the whole configuration file, i.e. only the configuration parameters that your service code accesses via app.conf.*.

Instead of in-lining it directly in the module, you can also store the configuration in the form of an ERB YAML template, in modules/<service-name>/templates/config.yaml.erb. Then, simply use it directly as the config parameter for the service::node resource like so:

        config          => template('<service-name>/config.yaml.erb'),

You will also need a role for your service. Put the following code fragment in manifests/role/<service-name>.pp:

# Role class for <service-name>
class role::<service-name> {

    system::role { 'role::<service-name>':
        description => 'short description',
    }

    include ::profile::<service-name>
}

and add the values for the hiera lookups in place inside hieradata/role/common/<service-name>.yaml as follows:

profile::<service-name>::param_name1: "some-value"
profile::<service-name>::param_name2: "some-other-value"

You can now submit the patch for review. Don't forget to mention the service request bug in your commit message.

Access rights

As the service owner and maintainer, you need to be able to log onto the nodes where your service is running. Once the exact list of target nodes is known, you need to file an access request ticket with the following information:

  • Ttile - access Request for <list-of-maintainers> for <service-name>
  • Description - <list-of-maintainers> needs access to <list-of-nodes> for operating <service-name>. We need to be able to read the logs at /srv/log/<service-name> and be able to start/stop/restart it. The task asking for the service's deployment is {<service-request-task-number>}

This request implies sudo rights on the target nodes, so you will need the approval from your manager on this task.