Intents and intents files

Intent-based access control is, not surprisingly, centered around declaring intents — specifically, declaring client intents to call servers.

The mechanism to declare client intents is with client intents files, or just "intents files" for short. This is a natural approach for agile, cloud-native organizations and initiatives:

• Intents files are declarative;
• Specifically, intents files declare what needs to happen (service A needs to access service B to do operation C) without specifying, or needing to know, how to accomplish this;
• Intents files align with rapid, distributed development because they only require the knowledge that client developers already have &mdash no need for the target server developers or admins to keep track of who needs to access them;
• The declarative approach thrives in cloud-native infrastructures where there are existing APIs to configure access control automatically.

Intents within intents files

An intent is a declaration by a specific client to call a specific server, optionally specifying more granular information about the call (e.g. the resource path and method for HTTP, the topic name and operation for Kafka). In other words, an intent is a tuple of client, server, and optional granular call information. If any of those changes, that's logically a different intent, though the intents file format allows some shorthand ways of aggregating intents that only differ by HTTP method or Kafka operation. See the example below.

An client's intents file specifies all the intents of that client, in one YAML file. Why is that important? Because as the client's needs change, the intents file should change with it, and any intents no longer needed should be removed from the file. When this updated file is applied, the corresponding access is also removed, i.e. the network policies or the Kafka ACLs that were previously in place due to those intents are now gone. In this way, access controls always reflect all of, and only, the latest intended access.

Intents file formats

Client intents files are independent of the infrastructure on which IBAC is deployed — indeed, they abstract away any tie-ins with infrastructures and implementations of access control.

As an example, let's look at the core of a client intents file for a service called checkoutservice. It declares that it will call the emailservice, the orderservice, and the ecomm-events Kafka service. It also provides more granular information for some of the calls:

service:
  name: checkoutservice
calls:
  - name: emailservice
    type: http
  - name: orderservice
    type: http
    resources:
      - path: /orders/*
        methods: [ get, post ]
  - name: ecomm-events
    type: kafka
    topics:
      - name: orders
        operations: [ produce ]

You can actually create and use such "plain" or "vanilla" intents files without any other metadata. Currently, Otterize only supports processing client intents via the Otterize OSS intents operator for Kubernetes, so you'll need to run the plain intents files through the Otterize CLI (otterize intents convert) to convert them into Kubernetes custom resource YAML files.

Within the context of a Kubernetes cluster, it's very natural to format intents files from the beginning as Kubernetes custom resources. These files are applied (kubectl apply) to the Kubernetes API, which validates them against a ClientIntents custom resource definition (CRD) and then hands them over to the Otterize intents operator, as expected of a Kubernetes ecosystem extension. The two formats are trivially related: the "plain" intents file contents are simply embedded in the spec section of the custom resource format.

Here is the same client intents file, now formatted as a Kubernetes custom resource YAML, so it can be applied directly via kubectl apply:

apiVersion: k8s.otterize.com/v1alpha2
kind: ClientIntents
metadata:
  name: checkoutservice
spec:
  service:
    name: checkoutservice
  calls:
    - name: emailservice
      type: http
    - name: orderservice
      type: http
      resources:
        - path: /orders/*
          methods: [ get, post ]
    - name: ecomm-events
      type: kafka
      topics:
        - name: orders
          operations: [ produce ]

Intents file specification

The core of a client intents file has 2 root-level fields (keys, in YAML):

• service (required): describes the client service that intends to make the calls in this file.

  • name (required): specifies the name of the client service.

• calls (required): describes the (server) services which the client intends to call.
  Its value is a list of key-value pairs, each describing a server service to be called. (The combination of client service, server service, and optionally any more granular information about the call forms an intent.)
  Each item in the list has the following fields:

  • name (required): specifies the name of the server service.
    The name can include the namespace of the server service, if different from the client service, separated by a dot ("."): server-name.server-namespace.

  • type (optional, case-insensitive): specifies the type of call to be made to the server.
    If present, the values can currently be http or kafka.
    The Otterize intents operator will manage network policies for all intents, regardless of type (including if no type is specified); it will also manage Kafka ACLs if the type is kafka; and in the future it will also manage HTTP access controls if the type is http.

  • topics (optional; only allowed if type is kafka): Specifies the list of Kafka topics to be called.
    Each item in the list has the following fields:

    • name (required): specifies the name of the topic.
    • operations (required): specifies the list of intended operations on that topic.
      Allowed values are: consume, produce, create, alter, delete, describe, cluster_action, describe_configs, alter_configs, idempotent_write, and all.

  • resources (optional; only allowed if type is http): Specifies the list of HTTP resources to be called.
    Each item in the list has the following fields:

    • path (required): specifies the HTTP path of the resource.
    • methods (required): specifies the list of intended operations on that topic.
      Allowed values are: get, post, put, patch, delete, options, trace, and connect.