Apicurio Chart Values Reference

This reference describes the Apicurio Registry v3 values the Axual Streaming chart exposes: the image settings, the Kafka init container, the Kafka connection, TLS, the web user interface, the ingress routes, the Auth Proxy sidecar and the application configuration passed through to Apicurio itself.

Type

Reference

Goal

Look up an Apicurio Registry value and what it does, while writing the Axual Streaming values.

Audience

Platform Operator writing or reviewing the apicurio-registry-v3 section of an Axual Streaming values.yaml.

When to use

While configuring Apicurio Registry, alongside the procedure that applies these values.

Apicurio Registry v3 is keyed apicurio-registry-v3 in the Axual Streaming chart. Every key the chart accepts, with its defaults, is in the generated Apicurio Helm Readme. The sections below cover the ones that need explanation.

For the procedure that enables the registry and applies a base configuration, see How to Enable Apicurio Registry.

Contents

The sections below cover each area in this reference:

Apicurio Registry Image Configuration

The image block overrides the global image values for Apicurio Registry alone, so the rest of the chart keeps the global configuration.

Set it in the following way:

values.yaml
apicurio-registry-v3:

  image:
    registry: "registry.axual.io"
    repository: "apicurio/apicurio-registry"
    tag: "3.3.0.Ax1"
    pullPolicy: "Always"
  imagePullSecrets:
    - name: [your-docker-credentials]

  # In Apicurio v3 the web UI runs as a separate container with its own image.
  # The image tag above is shared by both the registry and the UI containers.
  ui:
    image:
      registry: "registry.axual.io/docker.io"
      repository: "apicurio/apicurio-registry-ui"
This step is not required for the basic configuration of Apicurio Registry.

Kafka init container

Apicurio Registry v3 requires an init container to create the journal, snapshots and events topics and their Access Control Lists (ACLs) in the Kafka cluster. The init container takes the following values:

  • The apicurioPrincipal is the principal common name (CN) identifying the client certificate Apicurio Registry uses to produce to and consume from the schema topics. Depending on how the Kafka installation is configured, the principal is either the SSL chain or the CN

  • The replicationFactor is the replication factor of the topics used to store schemas

  • The minIsr is the minimum in-sync replicas of the topics used to store schemas

  • The tls Secrets needed to connect to the Kafka cluster. Re-use the Kafka cluster secrets

    • The keypairSecretName is the name of the existing keypair secret containing the keypair used for TLS

    • The keypairSecretKeyName is the key name within the secret containing the private key for TLS

    • The keypairSecretCertName is the certificate name within the secret containing the public key for TLS

    • The truststoreCaSecretName is the name of the existing secret containing the truststore for CA certificates

    • The truststoreCaSecretCertName is the certificate name within the secret containing the CA certificates for truststore

  • The resources is the resource requirements for the Kafka init container

Where Kafka validates ACLs over the full principal chain, give the whole chain, as in [0] CN=Root CA, [1] CN=Intermediate CA, [3] CN=schema-registry. Otherwise give the common name prefixed with CN:.

Set it in the following way:

values.yaml
apicurio-registry-v3:

  kafkaInitContainer:
    apicurioPrincipal: "[0] CN=Dummy Root, [1] CN=Dummy Intermediate, [2] CN=Apicurio Registry"
    replicationFactor: "3"
    minIsr: "2"
    tls:
      keypairSecretName: "brokers-keystore"
      keypairSecretKeyName: "brokers-keystore.key.name"
      keypairSecretCertName: "brokers-keystore.crt.name"
      truststoreCaSecretName: "brokers-truststore"
      truststoreCaSecretCertName: "brokers-truststore.crt.name"
    resources: {}

Kafka Configuration

The Kafka configuration section connects Apicurio Registry to the Kafka cluster. Both the Kafka init container and the Apicurio Registry container read these values:

  • The bootstrapServers is the list of Kafka bootstrap servers used by both the Kafka init container and the Apicurio Registry container.

  • The journalTopic, snapshotsTopic and eventsTopic are the fully resolved names of the three topics Apicurio v3 uses to store schemas and configuration (typically {tenant}-{instance}-journal, {tenant}-{instance}-snapshots and _{tenant}-{instance}-events)

  • The groupPatternOverride is the group prefix to give access to (typically {tenant}.{instance}.apicurio)

Here is an example:

values.yaml
apicurio-registry-v3:

  kafka:
    bootstrapServers: "[kafka-bootstrap-server]:[kafka-boostrap-server-port]"
    journalTopic: "_{tenant}-{instance}-journal"
    snapshotsTopic: "_{tenant}-{instance}-snapshots"
    eventsTopic: "_{tenant}-{instance}-events"
    groupPatternOverride: "{tenant}.{instance}.apicurio"

TLS Configuration

TLS needs Secrets holding the PEM certificates the chart generates the keystores from:

  • Server keypair

  • Client keypair

  • Truststore

To enable Basic Authentication, ensure that Apicurio’s truststore contains the required Certificate Authority (CA) for Keycloak.
values.yaml
apicurio-registry-v3:

  tls:
    # -- Existing server Keypair secret name
    serverKeypairSecretName: "[apicurio-registry-server-certificates]"
    # -- Existing client Keypair secret name
    clientKeypairSecretName: "[apicurio-registry-client-certificates]"
    # -- Existing truststore secret name
    truststoreCaSecretName: "[apicurio-registry-ca-certificates]"

For more information on the secrets defined above, refer to TLS Secret Formats Reference.

Web UI configuration

In Apicurio v3 the web UI is served by a separate container, which needs to know the public URL of the registry API.

ui.config.registryApiUrl is required: set it to the public HTTPS URL that browsers use to reach the API (for example https://apicurio.<domain>/apis/registry/v3). Do not use localhost. The browser resolves this URL, and the container never does.

values.yaml
apicurio-registry-v3:

  ui:
    config:
      # -- REQUIRED: public HTTPS URL the browser uses to reach the registry API
      registryApiUrl: "https://apicurio.<domain>/apis/registry/v3"
      # -- Authentication type: "oidc" or "none"
      authType: "oidc"
When the Auth Proxy is enabled, registryApiUrl names the ingress.ui hostname rather than the Auth Proxy hostname, for example https://apicurio-without-auth-proxy.<domain>/apis/registry/v3.

security.authentication.keycloak

The web UI logs in against the Apicurio Keycloak realm, and this block tells the registry which realm and client to send the browser to. It applies when security.authentication.enabled is true.

  • authUrl is the Keycloak authentication URL. Defaults to "".

  • realm is the Keycloak realm holding the Apicurio permissions and users. Defaults to "".

  • webClientId is the client ID for the Apicurio UI. Defaults to "". The realm the Axual Streaming charts import ships this client as apicurio-web.

  • webRedirectUrl is the Apicurio UI URL the browser returns to after login. Defaults to "". It is the ingress.ui hostname, which differs from the Auth Proxy hostname when the proxy is enabled.

values.yaml
apicurio-registry-v3:

  security:
    authentication:
      keycloak:
        authUrl: "https://[apicurio-keycloak-host]/auth"
        realm: "apicurio"
        webClientId: "apicurio-web"
        # -- The UI host, not the Auth Proxy host
        webRedirectUrl: "https://apicurio-without-auth-proxy.<domain>"
The hostname in webRedirectUrl is also allowed on the Keycloak client itself, which is a Keycloak setting rather than a chart value. See Allow the UI hostname on the Keycloak client.

Ingress routing reference

Apicurio v3 exposes its API and its web UI on separate ports of a single Kubernetes Service, and the chart splits the ingress accordingly: ingress.backend serves the API and ingress.ui serves the UI. They are path-separated (/apis vs /), so they can share one hostname.

Use the table below when configuring an external ingress, gateway, or OpenShift Route in front of Apicurio: each row is one entrypoint, with the target Service port and the path it must serve. All entrypoints route to the same Service, named after the chart’s fullname, typically <release-name>-apicurio-registry-v3 (overridable with nameOverride / fullnameOverride).

Ingress (values key) Path Target Service port Serves

ingress.backend

/apis (Prefix)

20500 (port name http)

Registry REST API, /apis/registry/v2, /apis/registry/v3 and /apis/ccompat/v7

ingress.ui

/ (Prefix)

20501 (port name ui-http)

Apicurio web console (static UI container)

authProxy.ingress

as configured, for example /apis (Prefix)

8082 (port name auth-proxy)

Auth Proxy sidecar (JWT + Basic Auth). Only when authProxy.enabled: true. It validates the request and forwards it to the backend at localhost:8081 inside the pod. See Point the Auth Proxy ingress at the clients' hostname.

When the Auth Proxy is enabled, route client and Governance (Platform Manager) traffic through authProxy.ingress (port 8082). The web UI must still reach the backend directly through ingress.backend (20500) and ingress.ui (20501), because the UI authenticates against the Apicurio Keycloak, whose tokens the Auth Proxy does not validate. See Move the backend and UI ingresses to a second hostname.

The 20500 and 20501 ports above are Service ports, set by service.httpPort and service.uiPort. They are independent of the ports the containers open inside the pod: the registry container listens on 8081, the web UI container on 8080, and the Auth Proxy on authProxy.port, which defaults to 8082.

ingress.backend and ingress.ui

Both ingresses take a single host string, an IngressClass name and a tls list, and both are disabled by default.

values.yaml
apicurio-registry-v3:

  ingress:
    backend:
      enabled: true
      className: nginx
      host: "apicurio-without-auth-proxy.<domain>"
      tls:
        - secretName: "[your-secret-name]"
          hosts:
            - "apicurio-without-auth-proxy.<domain>"
    ui:
      enabled: true
      className: nginx
      host: "apicurio-without-auth-proxy.<domain>"
      tls:
        - secretName: "[your-secret-name]"
          hosts:
            - "apicurio-without-auth-proxy.<domain>"

authProxy.ingress

authProxy.ingress takes a hosts list, with one or more paths per host, rather than the single host string the other two ingresses take. It is disabled by default and applies only when authProxy.enabled is true.

values.yaml
apicurio-registry-v3:

  authProxy:
    ingress:
      enabled: true
      className: nginx
      hosts:
        # -- The address clients already use, previously ingress.backend's host
        - host: "apicurio.<domain>"
          paths:
            - path: "/"
              pathType: "ImplementationSpecific"
      tls:
        - secretName: "[your-secret-name]"
          hosts:
            - "apicurio.<domain>"

Auth Proxy configuration

The Auth Proxy is a sidecar container that validates a JSON Web Token (JWT) or a Basic Auth credential in front of the registry. authProxy.enabled is false by default, and the keys below apply when it is true. What the sidecar does, and how each authentication flow reaches the registry, is described in Authentication and the Auth Proxy.

  • authProxy.port is the container port the proxy listens on. Defaults to 8082, and must differ from the registry container port (8081) and the web UI container port (8080) in the same pod.

  • authProxy.config is the full YAML mounted as the proxy’s /config/application.yml.

  • authProxy.config.server.port repeats the listening port and carries the same constraint. Defaults to 8082.

  • authProxy.config.auth-proxy.valid-issuer-uri is the issuer URI that incoming JWT tokens are validated against. Required, and defaults to "".

  • authProxy.config.auth-proxy.jwks-endpoint-uri is the JWKS endpoint the proxy fetches public keys from to verify a JWT signature. Required, and defaults to "".

  • authProxy.config.auth-proxy.client-id is the client ID, or audience, matched on an incoming JWT. Defaults to "".

  • authProxy.config.auth-proxy.backend-service is the registry the proxy forwards a validated request to, inside the same pod. Defaults to http://localhost:8081.

values.yaml
apicurio-registry-v3:

  authProxy:
    enabled: true
    # -- Must differ from the Apicurio backend (8081) and UI (8080) container ports
    port: 8082
    config:
      server:
        port: 8082
      auth-proxy:
        valid-issuer-uri: "https://[apicurio-keycloak-host]/auth/realms/[realm]"
        jwks-endpoint-uri: "https://[apicurio-keycloak-host]/auth/realms/[realm]/protocol/openid-connect/certs"
        client-id: ""
        backend-service: "http://localhost:8081"

For the procedure that enables the sidecar and routes traffic to it, see How to Enable the Apicurio Auth Proxy.

Auth Proxy secrets

authProxy.secrets holds the sensitive half of the proxy configuration and is mounted as /secrets/secrets.yml. The proxy derives the credential it presents to the registry for a Basic Auth client from the client’s username, the salt and the hash algorithm below.

  • authProxy.secrets.auth-proxy.client-secret-salt is the salt used in that derivation. It has no default, and each environment sets its own value. What the salt guarantees is described in Authentication and the Auth Proxy.

  • authProxy.secrets.auth-proxy.client-secret-algorithm is the hash algorithm. Optional, and defaults to HmacSHA256.

  • authProxy.existingSecretName names an existing Kubernetes Secret to mount in place of the inline secrets values. The Secret holds a key named secrets.yml. Defaults to "". For the procedure, see How to Store Component Credentials in a Kubernetes Secret.

secrets.yaml
apicurio-registry-v3:

  authProxy:
    secrets:
      auth-proxy:
        client-secret-salt: "[change-me]"
        client-secret-algorithm: HmacSHA256

An installation that keeps the salt out of its values file names an existing Secret instead.

values.yaml
apicurio-registry-v3:

  authProxy:
    existingSecretName: "[your-existing-secret-name]"
The salt is a credential. Each environment has its own value, and it does not belong in version control.

Application Configuration

Apicurio Registry is a Quarkus application, and a Quarkus application reads its configuration properties from application.properties. The chart injects everything under config into a ConfigMap and mounts it as that file. Apicurio v3 uses the apicurio.* property prefix.

Wrap a boolean value in double quotes, or it does not reach the application.properties file correctly.

These options tune the behaviour of Apicurio Registry, as shown in the example below.

values.yaml
apicurio-registry-v3:

  config:
    apicurio.ccompat.use-canonical-hash: "true"
    apicurio.ccompat.legacy-id-mode.enabled: "false"
    apicurio.auth.anonymous-read-access.enabled: "false"
    apicurio.auth.role-based-authorization: "true"
    apicurio.auth.owner-only-authorization: "true"
    apicurio.auth.admin-override.enabled: "true"
In a production environment, set apicurio.auth.anonymous-read-access.enabled to "false" and grant read access through the sr-readonly role instead.