Skip to content

Declarative Configuration

Configuring your figgy.json file#

Please do not be overwhelmed, most of your figgy.json can be autogenerated. Check out our shared libraries!

If you have not yet read Figgy Concepts, please do so before continuing.

Your figgy.json file is parsed by the sync, cleanup. and validate commands. This file is necessary to support many advanced Figgy features such as breaking-builds for missing parameters.

Right now the following properties are supported:

Here are the purposes of each property:

twig#

The twig property is required

This property should be set to your service's twig. I.E. /app/your-service-name or /svc/your-service-name

   "twig": "/app/message-processor"

If you set the twig property, you may omit your twig's prefix (I.E. /app/service-name from your app_figs values.


app_figs#

The app_figs property is optional.

Here you will define the figs your app requires to operate. These fig names will always begin with twig namespace.

An example fig might be: /app/message-processor/log-level.

Sample app_figs config block:

   "app_figs": [
      "/app/message-processor/log-level",
      "/app/message-processor/api-key", 
      "/app/message-processor/batch-size", 
      "/app/message-processor/worker-count",
   ] 

For simpler configuration, you may instead structure the above block like this:

   "app_figs": [
      "log-level",
      "api-key", 
      "batch-size", 
      "worker-count"
   ] 

replicate_figs#

replicate_figs is an optional property.

A replicate_figs configures replication from the /shared namespace in to your application's configuration namespace. For instance, if you wanted your app to leverage a shared sql host and database name, you'd want to add a replication config section as follows:

Sample replicate_figs block:

    "replicate_figs": { 
        "/shared/data/sql/hostname" :  "/app/message-processor/replicated/sql/hostname", 
        "/shared/data/sql/db_name" :  "/app/message-processor/replicated/sql/db_name" 
    }

The replication config is a MAP of SOURCE (STR) DEST (STR). In the above example, the value of

/shared/data/sql/hostname

will be replicated to

/app/message-processor/replicated/sql/hostname

automagically. To replicate parameters into your twigs namespace, run

figgy config sync --config figgy.json

Once configured, replication is automatic. Any updates to the SOURCE will automatically trigger updates to all downstream destinations.

shared_figs#

The shared_figs property is optional.

Shared figs define what should have been shared with your application by an outside party. These figs are typically secrets shared by a secret owner, such as a DBA or the DevOps team.

For instance, suppose application message-processor requires various mongo connection configurations which are shared with it by a Mongo DBA. Here you can define those shared configurations.

Sample shared_figs config block:

  "shared_figs": [ 
      "/app/message-processor/replicated/mongo/user", 
      "/app/message-processor/replicated/mongo/pass", 
      "/app/message-processor/replicated/mongo/data_source", 
      "/app/message-processor/replicated/mongo/replica_set", 
      "/app/message-processor/replicated/mongo/options"
  ]

The validate command can be used to validate these shared values exist before allowing the CICD build to complete. This will prevent inadvertent deployments destined to fail.


merge_figs#

The merged_figs property is optional.

Merged figs enable you to merge multiple other figs into a single merged_fig.

Merge figs require are a Map of type KEY (STR) VALUE (List[STR]). In the value, you may define a list of strings. These strings will be combined in the order defined to generate a merged fig.

merged_figs: {
   "/app/message-processor/replicated/sql/conn_string": 
        [ 
          "db://",
          "${/app/message-processor/replicated/sql/db/user:uri}", 
          ":", 
          "${/app/message-processor/replicated/sql/db/password:uri}",
          "//", 
          "${/app/message-processor/replicated/sql/db_name}"
        ]
    }

The resulting value at /app/message-processor/replicated/sql/conn_string will look something like this: db://message-processor:password//processor-db

Options:

  • The :uri suffix may be applied to indicate that the resulting merge-value should have this part of the fig as URI Encoded.

Requirements:

  • The destination, in this case /app/message-processor, must be in your service's twig as defined above.

Figgy will maintain this merged configuration for you and will ensure your merged configuration is synchronized with all of the configurations that it depends on.

Merge Template



replicate_from#

The replicate_from property is optional.

This block enables users to replicate a series of parameters from another namespace under the same Fig Tree.

This is particularly useful when you might want to deploy a single service multiple times into the same environment with slightly differing configurations (perhaps multiple feature branches?)

For instance, suppose you want to deploy application message-processor under a new name of message-processor-test but don't want to manually copy and manage configs between /app/message-processor and /app-message-processor-test. The replicate_from key can be leveraged to synchronize various configurations between /app/message-processor and /app-message-processor-test.

In the below example, any changes to person_name, secret_admirer, or maintenance_enabled under /app/message-processor will automatically be updated under /app/message-processor-test. This way a single service can easily be deployed redundantly in a single environment without the hassle of managing duplicate configurations between the various deployments.

Sample replicate_from config block:

   "twig": "/app/message-processor-test/", 
   "replicate_from": {
      "source_twig": "/app/message-processor/", 
      "figs": [
          "person_name", 
          "secret_admirer", 
          "maintenance_enabled"
     ]
}



Here is a sample fully functioning figgy.json file that leverages all properties:

{
    "twig": "/app/message-processor/", 
    "replicate_figs": {
        "/shared/data/sql/hostname" : "/app/message-processor/replicated/shared/sql/hostname",
        "/shared/data/sql/db_name" : "/app/message-processor/replicated/sql/db_name"
    },
    "app_figs": [ 
        "config1", 
        "config3", 
        "config6"
    ], 
    "shared_figs": [
        "replicated/mongo/user", 
        "replicated/mongo/pass", 
        "replicated/mongo/data_source", 
        "replicated/mongo/replica_set", 
        "replicated/mongo/options"
    ], 
    "replicate_from": {
        "source_twig": "/app/potato-processor/", 
        "figs": [
            "person_name",
            "secret_admirer",
            "maintenance_enabled"
        ] 
    },
    "merged_figs": {
        "/app/message-processor/replicated/sql/conn_string": 
            [ 
              "db://",
              "${/app/message-processor/replicated/sql/db/user:uri}", 
              ":", 
              "${/app/message-processor/replicated/sql/db/password:uri}",
              "//", 
              "${/app/message-processor/replicated/sql/db_name}"
            ]
        }
    }
}



The following parameters would need to exist in ParameterStore to pass validation:

/app/message-processor/replicated/shared/sql/hostname
/app/message-processor/replicated/sql/db_name
/app/message-processor/config1
/app/message-processor/config3
/app/message-processor/config6
/app/message-processor/replicated/mongo/user
/app/message-processor/replicated/mongo/pass 
/app/message-processor/replicated/mongo/data_source
/app/message-processor/replicated/mongo/replica_set 
/app/message-processor/replicated/mongo/options
/app/message-processor/person_name
/app/message-processor/secret_admirer
/app/message-processor/maintenance_enabled
/app/message-processor/replicated/sql/conn_string