Rule Sets

Rule Sets organize rules, allowing versioning of such and loading by providers.

Depending on the configured provider, the rules can be then loaded from e.g. a plain old configuration file, residing in the local file system, or even from a Kubernetes environment as a custom resource. Thus, the structure and format of a rule set depends on the provider used to load it. As of today, there are two supported formats:

as a regular JSON/YAML file, the so-called regular rule set, and
as a kubernetes custom resource rule set, which is actually a YAML/JSON file as well, but adheres to corresponding kubernetes requirements.

The main difference is the internal structure. Both do however require the specification of a version and a list or rules.

Regular Rule Set

A regular rule set is a just a file with a list of rules and some additional meta information. Latter can be extended by a particular provider supporting that format.

Available properties are:

version: string (mandatory)
The version schema of the rule set. The current version of heimdall supports only the version 1alpha4.
name: string (optional)
The name of a rule set. Used only for logging purposes.
rules: Rule Configuration array (mandatory)
The list of the actual rule definitions.

Example 1. Rule set with two rules

An imaginary rule set file defining two rules could look like shown below.

version: "1alpha4"
name: my-rule-set
rules:
- id: rule:1
  match:
    routes:
      - path: /**
    methods: [ "GET" ]
    scheme: https
    hosts:
      - type: exact
        value: my-service1.local
  execute:
    - authorizer: foobar
- id: rule:2
  match:
    routes:
      - path: /**
    scheme: https
    hosts:
      - type: exact
        value: my-service2.local
    methods: [ "GET" ]
  execute:
    - authorizer: barfoo

Kubernetes Rule Set

If you operate heimdall in kubernetes, most probably, you would like to make use of the RuleSet custom resource, which can be loaded by the kubernetes provider.

Configuration

apiVersion: string (mandatory)
The api version of the custom resource definition, the given rule set is based on. The current version of heimdall supports only heimdall.dadrus.github.com/v1alpha4 version.
kind: string (mandatory)
The custom resource kind. Must be set to RuleSet
metadata: map (optional)
The metadata, you would like to assign to the rule set, like the name of the rule set, labels, etc
spec: map (mandatory)
The actual specification of the rule set. Following properties are possible, respectively required:
- authClassName: string (optional)
  References the heimdall instance, which should use this RuleSet.
- rules: Rule Configuration array (mandatory)
  The list of the actual rules.

To be able to deploy and make heimdall use the RuleSet custom resources, the corresponding CRD must be deployed. Otherwise, heimdall will not be able to monitor corresponding resources and emit error messages to the log.

If you have used the Helm Chart to install heimdall, this CRD is already installed. You can however install it also like this:

$ kubectl apply -f https://raw.githubusercontent.com/dadrus/heimdall/main/charts/heimdall/crds/ruleset.yaml

Example 2. Simple Example

apiVersion: heimdall.dadrus.github.com/v1alpha4
kind: RuleSet
metadata:
  name: "<some name>"
spec:
  authClassName: "<optional auth_class reference (see above)> "
  rules:
    - id: "<identifier of a rule 1>"
      match:
        routes:
          - path: /foo/**
        scheme: https
        hosts:
          - type: exact
            value: 127.0.0.1:9090
      execute:
        - authenticator: foo
        - authorizer: bar

Resource Status

In addition to configuration properties described above, a RuleSet resource has a status stanza, which provides information about the usage status as soon as a RuleSet has been loaded by at least one heimdall instance.

By making use of kubectl get -n <your namespace> rulesets.heimdall.dadrus.github.com you’ll get an overview of deployed RuleSet resources in a particular namespace, like e.g. shown below

NAME             ACTIVE IN       AGE
test-rules       2/2             32m

The value 2/2 in ACTIVE IN means, <active in heimdall instances>/<matching instances>. With

"matching instances" being those heimdall instances, which auth_class matches the authClassName in the RuleSet and
"active in heimdall instances" are those from the "matching instances", which were able to load the RuleSet.

In addition, you can also get further information about the executed reconciliations by the deployed heimdall instances by taking a look at the .status.conditions field. The reconciliation status of matching instances is present there. That also means, if there were errors while loading the RuleSet, these are present in this condition list

E.g.

$ kubectl describe -n test rulesets.heimdall.dadrus.github.com test-rules

Name:         test-rules
Namespace:    test
...
Status:
  Conditions:
    Last Transition Time:  2023-11-08T21:55:36Z
    Message:               heimdall-6fb66c47bc-kwqqn instance successfully loaded RuleSet
    Observed Generation:   1
    Reason:                RuleSetActive
    Status:                True
    Type:                  heimdall-6fb66c47bc-kwqqn/Reconciliation
    Last Transition Time:  2023-11-08T21:55:36Z
    Message:               heimdall-6fb66c47bc-l7skn instance successfully loaded RuleSet
    Observed Generation:   1
    Reason:                RuleSetActive
    Status:                True
    Type:                  heimdall-6fb66c47bc-l7skn/Reconciliation
  Active In:               2/2
  Events:                  <none>

Last updated on Sep 11, 2024

Default Rule Rule Providers