Rule definitions are managed via the Amalgam8 controller’s REST API. A simple commandline interface that calls this REST API is available for basic use cases. The CLI documentation is available here. However, for more advanced functionality or defining rules programmatically, the controller API supports a powerful Rules DSL and can be called directly.

The following describes basic invocation of the controller REST API using curl with the utility jq to format the output json. For these commands we assume that the controller is running in global authorization mode so that no authentication is required.

There are two basic types of rules,

  • routing
  • action

Routing rules

Routing rules define routing behavior. For example:

  • Route 75% of requests to ServiceA v1 and the remaining 25% to v2.

Routing rules are useful for canary testing, red/black deployments. The rule described above can be added via a call to the controller REST API:

curl -X POST <controller URL>/v1/rules -H 'Accept: application/json' --data '{"rules": [{"priority": 1, "route": {"backends": [{"weight": 0.25, "tags": ["v2"]}, {"tags": ["v1"]}]}, "destination": "serviceA"}]}' | jq .

Output:

{
  "ids": [
    "b3d6cb84-4676-4bc8-8f84-c9f56f99b63d"
  ]
}

The API returns the ID of the newly added rule.

As you can see, the Amalgam8 controller REST API allows for powerful dynamic route definitions.

Action rules

Action rules define actions that should be performed in specific circumstances. For instance:

  • Delay all requests from ServiceA v2 to ServiceB v1 by 7 seconds

Action rules are useful for testing deployments. The rule described above can be added via a call to the controller REST API:

curl -i -X POST <controller URL>/v1/rules -H 'Accept: application/json' --data '{"rules": [{"priority": 10, "destination": "serviceB", "actions": [{"action": "delay", "duration": 7.0, "probability": 1.0, "tags": ["v1"]}], "match": {"source": {"name": "serviceA", "tags": ["v2"]}}}]}' | jq .

Output:

{
  "ids": [
    "74dd54f8-706c-43b2-b229-8c465d19952c"
  ]
}

Listing and deleting rules

To list rules, the following curl command can be used:

curl <controller URL>/v1/rules | jq .

The output of the above command should look like this:

{
  "rules": [
    {
      "id": "74dd54f8-706c-43b2-b229-8c465d19952c",
      "priority": 10,
      "destination": "serviceB",
      "match": {
        "source": {
          "name": "serviceA",
          "tags": [
            "v2"
          ]
        }
      },
      "actions": [
        {
          "action": "delay",
          "duration": 7,
          "probability": 1,
          "tags": [
            "v1"
          ]
        }
      ]
    },
    {
      "id": "b3d6cb84-4676-4bc8-8f84-c9f56f99b63d",
      "priority": 1,
      "destination": "serviceA",
      "route": {
        "backends": [
          {
            "weight": 0.25,
            "tags": [
              "v2"
            ]
          },
          {
            "tags": [
              "v1"
            ]
          }
        ]
      }
    }
  ],
  "revision": 2
}

Individual rules can be queried by ID or tag.

curl <controller URL>/v1/rules?id=b3d6cb84-4676-4bc8-8f84-c9f56f99b63d | jq .

Output:

{
  "rules": [
    {
      "id": "b3d6cb84-4676-4bc8-8f84-c9f56f99b63d",
      "priority": 1,
      "destination": "serviceA",
      "route": {
        "backends": [
          {
            "weight": 0.25,
            "tags": [
              "v2"
            ]
          },
          {
            "tags": [
              "v1"
            ]
          }
        ]
      }
    }
  ],
  "revision": 2
}

Similarly, rules can be removed by ID or tag.

curl -i -X DELETE <controllerURL>/v1/rules?id=b3d6cb84-4676-4bc8-8f84-c9f56f99b63d

If no query parameters are provided, all the rules are deleted.

curl -i -X DELETE <controller URL>/v1/rules

Full documentation

Detailed documentation on the route controller’s REST API can be found here.

Rules passed to the controller conform to the A8 Rules DSL and are validated against a JSON schema definition that is available here.

Service references in rules vs services registered in registry

Amalgam8 controller rule definitions reference services. The Amalgam8 registry also keeps track of active services. However, the services referenced in Amalgam8 controller rules and the services registered in the Amalgam8 registry are independent.

  • Registry services: are composed of transient endpoints that are registered and maintained by heartbeats from sidecars. Registry endpoints (and therefore the services they are part of) may appear or disappear due to networking, crashes, new deployments, etc.

  • Service references in controller rules: are references to a service that may or may not currently exist in registry.

This separation allows routing and other rules to be defined independently of the current state of the environment. Rules are not removed because the service they reference is down. Likewise, rules may reference services that have not yet been registered or no longer exist.