Know Your Service Definition

Introduction

A service is an atomic unit of deployment. It is meant to package a business functionality as a unit, though, the user can define it as per their use case. A service is composed of multiple components. In this article, we are going to discuss the details of the service definition that can be used in Odin. Following will be the items covered here:

  1. Parameters in Service definition

  2. How to add a new component in the service

  3. Modify a component in a service

  4. Route 53 creation using Odin

Parameters in Service Definition

While defining a service there are couple of mandatory fields that we have to include. A service can be uniquely identified with its name and version. Hence, name and versions are two mandatory fields along with team and components:

– Name: Name field is used to define the name of the service and the service will be identified with this name. E.g: In this service definition, the service can be identified with the name “MyAuth“.

– Version: Version field is used to define the service version you are deploying. E.g: In this service definition, the version of the service is “1.0.0“.

– Team: Team field is used to define the team name that owns the service. E.g: In this service definition, the team name of the service is “tech“.

– Components: Your service needs a certain set of components to successfully run the service. This is where we define the set of components, their versions needed for the service, and other mandatory parameters needed for the components to be successfully operational. E.g: In this service definition, the service MyAuth needs three components to successfully operate - “application“, “cassandra“, and “aerospike“.

– Artifact name & version: A component details should be having the artifact name and the version for the same. The artifact name and versions may or may not be same as component name and versions respectively. It is highly recommended to provide the details in service definition though these are optional fields. In case you are not providing these details, Odin will assume that the artifact name and version are same as that of the component. E.g: In this service definition, for the component application, artifact name and version have been provided as part of the application config which are test and 1.0.0 respectively.

How to add a new component in a service

There might be situations when your service needs a new component and the same needs to be added in the service definition. We can follow the below steps to add a new component to the service definition:

  • Verify if the new component you are trying to add is supported by Odin by using the following command. If you do not see your component in the list, please reach out to us @dss_odin_feedback.

odin list component-type

  • If your component type is supported by Odin, use the following command to view the component description. With the component description, we can see the configurations for the components that one can override. For example, see the sample component definition for S3 here - S3 Component Definition.

odin describe component-type --name COMPONENT_NAME

  • Once we have the list of exposed components, we can see the exposed configs for the particular components. For example, following are the list of configs which can be altered for the component S3. In the second column, we can see if that particular configuration is mandatory or optional to include in your service definition.

List of exposed configs :

  CONFIG               | MANDATORY | DATA TYPE  
-----------------------+-----------+------------
  config.access        | false     | string     
  config.bucket_name   | true      | string     
  config.force_destroy | false     | string     
  config.versioning    | false     | string     
  name                 | true      | string     
  type                 | true      | string     
  version              | true      | string

  • Include one more block within the components section of the service definition and change the mandatory configs within the same in the following manner. The service definition will now start deploying the new component as well.

"components": [
    {
      "type": "s3",
      "name": "new-components",
      "version": "1.0.0",
      "config":{
      "artifact_name": "arc_s3",
      "artifact_version": "1.0.0.1",
      "versioning": "PROVIDE VERSIONING",
      "force_destroy" : "PROVIDE VALUES"
      }
    },

Modifying a component in a service

As part of service definition, one can change the component configuration. However, the same is limited to the configs which are exposed as part of component definition. E.g: as mentioned in the above segment, some of the exposed configs for s3 component are access, bucket_name, versioning etc. One can alter these configs and modify the component configuration within a service definition.

Please note, given a change in component definition within the service is altering the service definition, you need to update the service version to the next version compared to its current.

________________________________________________________________________________________________

Note:

Customise Route53 using Odin

Route 53 is created in Odin by default as part of its behaviour. As an Odin user, one can alter the route 53 configuration. Route is part of your application component. The process is very similar to modifying a component in a service. To illustrate, please follow the below steps:

  • To view the application definition, use the following command to see the exposed configs:

odin describe component-type --name application

  • Once you type the above command, the following table is going to be a part of the output. As you can see, route is a configurable exposed configs:

List of exposed configs :

  CONFIG                    | MANDATORY | DATA TYPE  
----------------------------+-----------+------------
  config.artifact_name      | false     | string     
  config.artifact_version   | false     | string     
  config.build_type         | true      | string     
  config.build_version      | true      | string     
  config.discovery          | false     | string     
  config.liveness_endpoint  | false     | string     
  config.loadbalancer-type  | false     | string     
  config.port               | false     | integer    
  config.readiness_endpoint | false     | string     
  config.route.private      | false     | string     
  config.route.public       | false     | string     
  default.deployment_type   | false     | string     
  dev.deployment_type       | false     | string     
  load.deployment_type      | false     | string     
  load.params.instance_type | false     | string     
  load.params.lb_type       | false     | string     
  name                      | true      | string     
  type                      | true      | string     
  version                   | true      | string

  • Next, go to your service definition and in the component type application under the config section, add the route configuration. You can use TEAM_SUFFIX and VPC_SUFFIX in the route53, these variables will be replaced at runtime.

"components": [
    {
      "type": "application",
      "name": "profile",
      "version": "1.0.0-QA-SNAPSHOT",
      "config": {
        "artifact_name": "test",
        "artifact_version": "1.0.0",
        "build_type": "java",
        "build_version": "8"
        "route":{
          "private": "profile-app$TEAM_SUFFIX.dream11$VPC_SUFFIX.local"
        }
      }
    }
PreviousServiceNextVersioning

Last updated