In dev and test mode the extension starts a Topaz container and points the client at it. It needs a container runtime (Docker or Podman).

When it starts

The Dev Service runs unless one of these holds:

  • quarkus.topaz.devservices.enabled=false;

  • quarkus.topaz.authorizer.host or quarkus.topaz.directory.host is set, meaning you point at your own Topaz;

  • no container runtime is available (a warning is logged).

Once the container is up, the application receives quarkus.topaz.authorizer.host and .port, quarkus.topaz.directory.host and .port, quarkus.topaz.plain-text=true, quarkus.topaz.api-key when quarkus.topaz.devservices.api-key is set, and quarkus.topaz.console-url when the console is enabled. The container listens in plaintext, so no trust store is needed.

Settings

All keys are fixed at build time. The configuration reference lists their types and defaults.

Key Effect

quarkus.topaz.devservices.enabled

Turns the Dev Service off when false.

quarkus.topaz.devservices.image-name

Topaz image. Defaults to ghcr.io/aserto-dev/topaz:0.33.22, the version this extension is tested with.

quarkus.topaz.devservices.policy.directory

Directory of Rego files loaded as a local bundle.

quarkus.topaz.devservices.policy.image

OCI policy image pulled from ghcr.io, such as ghcr.io/aserto-policies/policy-todo:latest.

quarkus.topaz.devservices.manifest-location

Directory manifest YAML loaded after start.

quarkus.topaz.devservices.data-location

Directory with objects.json and/or relations.json imported after the manifest.

quarkus.topaz.devservices.api-key

Makes the container require this API key (except for Info and gRPC reflection) and configures the client to send it.

quarkus.topaz.devservices.container-env."env-name"

Extra environment variables for the container.

quarkus.topaz.devservices.console-enabled

Exposes the Topaz console and sets quarkus.topaz.console-url.

quarkus.topaz.devservices.shared

Shares the container between applications in dev mode.

quarkus.topaz.devservices.service-name

Value of the quarkus-dev-service-topaz label used to find a shared container.

Locations accept classpath: (copied under the build output directory, also from jars), filesystem: or a plain path. A location that does not exist fails the build.

Policies: directory or image

Set at most one of the two policy keys; setting both fails the build.

policy.directory is the choice for policies that live in your repository: the Rego files are copied into the container when it starts and loaded as a local bundle without signature verification.

policy.image is the choice for a policy already published as an OCI image, the way Topaz templates ship theirs. Topaz pulls it from ghcr.io at start.

With neither, Topaz starts without a policy and authorizer Is calls fail until one is loaded.

Manifest and data formats

The manifest is a Topaz directory manifest (model version 3):

model:
  version: 3
types:
  user: {}
  identity:
    relations:
      identifier: user
  todo:
    relations:
      owner: user
    permissions:
      can_delete: owner

The data directory holds Topaz’s export format: objects.json as {"objects": […​]} and relations.json as {"relations": […​]}. Entries are directory Object and Relation messages in their JSON form:

{"objects": [
  {"type": "user", "id": "rick@the-citadel.com", "display_name": "Rick Sanchez"},
  {"type": "identity", "id": "rick@the-citadel.com"},
  {"type": "todo", "id": "todo-1"}
]}
{"relations": [
  {"object_type": "identity", "object_id": "rick@the-citadel.com", "relation": "identifier",
   "subject_type": "user", "subject_id": "rick@the-citadel.com"},
  {"object_type": "todo", "object_id": "todo-1", "relation": "owner",
   "subject_type": "user", "subject_id": "rick@the-citadel.com"}
]}

The files are parsed strictly when the application builds: an unknown field or a malformed entry fails the build rather than the first request. Objects are imported before relations. An import error reported by Topaz fails startup.

The identity objects with identifier relations are what lets IdentityContexts.subject(…​) resolve a caller; see identity contexts.

Shared containers

In dev mode with shared=true, an application first looks for a running container labelled quarkus-dev-service-topaz with its service-name and reuses it instead of starting one. A reused container is not re-seeded. If a manifest-location is configured and the shared container’s manifest differs from it, a warning is logged and the shared manifest stays as it is. Stop the shared container, or set quarkus.topaz.devservices.shared=false, to load yours. A Topaz service started by Compose Dev Services is discovered the same way.

Rootless Podman

Testcontainers reaches rootless Podman through its user socket, with the Ryuk reaper disabled:

export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true
systemctl --user enable --now podman.socket

Scratch files of the Dev Service (the generated Topaz config, copies of classpath locations) go under the build output directory in topaz-devservices/.