Configure Axual Schema Registry

This page outlines the configuration values for Axual Schema Registry deployed via Axual Streaming Helm chart.

About Axual Schema Registry

Axual Schema Registry is a runtime server system that stores a specific set of artifacts as files. Axual Schema Registry enables you to add, update, and remove the artifacts from the store using a REST API. It is based on the last open-source Confluent Schema Registry and contains some schema interoperability features for support clients of different programming languages.

Axual Schema Registry Configuration

When configuring Axual Schema Registry in an Axual Streaming chart installation, you can refer to the following basic configuration and examples to build your own values.yaml file. For more details and advanced configuration, please refer to the Confluent Documentation of the version on which Axual Schema Registry is based.

Schema Registry image Configuration

You have the flexibility to override global values by specifying image configurations. This allows you to customize image-related parameters for Axual Schema Registry while maintaining a default global configuration.

You can configure it in the following way:

values.yaml

axual-schema-registry:

  image:
    registry: "docker.axual.io"
    repository: "axual/schemaregistry"
    tag: "5.7.1"
    pullPolicy: "IfNotPresent"
  imagePullSecrets:
    - name: docker-credentials

Kafka init container

Axual Schema Registry requires an init container to create topics and ACLs in the Kafka cluster. For init container, we need to specify:

The masterPrincipal is the master common name identifying the client-certificate used by SchemaRegistry Master to produce and consume from schemas topic. We might need to use the SSL chain to identify the master principal or the CN, depending on how the Kafka installation is configured
The slavePrincipal is the slave common name identifying the client-certificate used by SchemaRegistry Slave used to consume from schemas topic. We might need to use the SSL chain to identify the slave principal or the CN
The distributorPrincipal is the principal common name identifying the client-certificate used by Distributor to produce and consume from schemas topic We might need to use the SSL chain to identify the distributor principal or the CN
The replicationFactor is the replication factor of the topic used to store schemas
The minIsr is the minimum in-sync replicas of the topic used to store schemas
The tls Secrets needed to connect to the Kafka cluster; we suggest to 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

If Kafka is configured to validate ACLs over the full principal chain, please provide the principal chain as this example: [0] CN=Root CA, [1] CN=Intermediate CA, [3] CN=schema-registry. Otherwise, just provide the common name prefixed with CN:.

You can configure it in the following way:

values.yaml

axual-schema-registry:

  kafkaInitContainer:
    masterPrincipal: "[0] CN=Dummy Root, [1] CN=Dummy Intermediate, [2] CN=Schema Registry Master"
    slavePrincipal: "[0] CN=Dummy Root, [1] CN=Dummy Intermediate, [2] CN=Schema Registry Slave"
    distributorPrincipal: "[0] CN=Dummy Root, [1] CN=Dummy Intermediate, [2] CN=Distributor"
    replicationFactor: "1"
    minIsr: "1"
    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 is crucial for establishing communication between the Axual Schema Registry and the Kafka cluster. These configurations are used by both the Kafka init container and the Schema Registry container. You can define Kafka configuration in the following way.

The bootstrapServers is the list of Kafka bootstrap servers used by both the Kafka init container and the Axual Schema Registry container. Ensure that the specified bootstrap servers are accessible and configured with the appropriate protocol (Currently the Axual Schema Registry can only interact over SSL with the Kafka brokers)
The schemasTopic is the fully resolved name of the topic used to store schemas (typically _{tenant}-{instance}-schemas)
The groupPatternPrefix is the group prefix to give access to (typically {tenant}-{instance}-schema-registry-)

Here is an example:

values.yaml

axual-schema-registry:

  kafka:
    bootstrapServers: "SSL://kafka-bootstrap:9093"
    schemasTopic: "_tenant-instance-schemas"
    groupPatternPrefix: "tenant-instance-schema-registry-"

TLS Configuration

To use TLS for Schema Registry, it is necessary to specify the names of the existing secrets in the provided configuration for:

Server keypair
Client keypair
Truststore

values.yaml

axual-schema-registry:

  tls:
    master:
      # -- Existing server Keypair secret name
      serverKeypairSecretName: "schema-registry-master-server-certificates"
      # -- Existing client Keypair secret name
      clientKeypairSecretName: "schema-registry-master-client-certificates"
      # -- Existing truststore secret name
      truststoreCaSecretName: "schema-registry-master-ca-certificates"
    slave:
      # -- Existing server Keypair secret name
      serverKeypairSecretName: "schema-registry-slave-server-certificates"
      # -- Existing client Keypair secret name
      clientKeypairSecretName: "schema-registry-slave-client-certificates"
      # -- Existing truststore secret name
      truststoreCaSecretName: "schema-registry-slave-ca-certificates"

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

Schema Registry Configuration Overrides

This configuration overrides section provides a way to override specific configurations for the Axual Schema Registry. These settings are customizable for both the master and slave components of the Schema Registry.

The configuration options allow you to fine-tune the behavior of the Axual Schema Registry. For a comprehensive list of available configuration options, please refer to the Confluent Official website.

You can customize the configuration of the Schema Registry according to your requirements, as shown in the example below.

values.yaml

axual-schema-registry:

  configurationOverrides:
    master:
      kafkastore.security.protocol: 'SSL'
      kafkastore.ssl.enabled.protocols: 'TLSv1.2'
      kafkastore.ssl.cipher.suites: ''
      ssl.cipher.suites: ''
      authentication.method: 'NONE'
      ssl.enabled.protocols: 'TLSv1.2'
      heap.opts: "-Xms512M -Xmx512M"
    slave:
      kafkastore.security.protocol: 'SSL'
      kafkastore.ssl.enabled.protocols: 'TLSv1.2'
      kafkastore.ssl.cipher.suites: ''
      ssl.cipher.suites: ''
      authentication.method: 'NONE'
      ssl.enabled.protocols: 'TLSv1.2'
      heap.opts: "-Xms512M -Xmx512M"

Please be aware that the Axual Schema Registry is based on the Confluent Schema Registry client version 4.1.3, so the configuration provided here reflects the available settings of that specific version.

Client authentication (mTLS)

With mTLS (mutual TLS), during the TLS handshake, the following happens:

The SR server presents a certificate to the client, the client will allow the connection if the certificate is signed by a CA that the client trusts
The client presents a certificate to the server, the server will allow the connection if the certificate is signed by a CA that the server trusts

In this way, both the client and the server are authenticated. It is possible to enable mTLS with the configuration:

values.yaml

axual-schema-registry:

  configurationOverrides:
    master:
      ssl.client.auth: 'true'
      ssl.client.auth.need: 'true'
    slave:
      ssl.client.auth: 'true'
      ssl.client.auth.need: 'true'

You can disable mTLS by setting the values to false or by omitting the configuration. Without mTLS, during the TLS handshake, the following happens:

The SR server presents a certificate to the client, the client will allow the connection if the certificate is signed by a CA that the client trusts

Basic Auth configuration

Using Basic Auth in a production environment is strongly discouraged

Schema registry supports Basic Auth, which is disabled by default. To enable it, first, configurationOverrides should specify authentication.method: 'BASIC' and second, secret names should be provided.

Secret should contain username and password fields

values.yaml

security:
  master:
    basicAuth:
      secretName: "basic-auth-secret-master"
  slave:
    basicAuth:
      secretName: "basic-auth-secret-slave"

configurationOverrides:
  master:
    authentication.method: 'BASIC'
  slave:
    authentication.method: 'BASIC'

If both mTLS and Basic Auth are used, Basic Auth will be considered disabled.

Logback Configuration

The chart comes pre-configured with a default logback setup utilized by the Axual Schema Registry application. This configuration includes settings for:

pattern: Specifies the precise pattern for log statements.
rootLoglevel: Establishes the foundational logging level.
loggers: You can configure specific loggers with different levels, overriding the root level for these loggers.

While it is not mandatory to supply this configuration, you have the option to use the provided configuration for customization purposes. Here is a default configuration:

values.yaml

axual-schema-registry:

  logging:
    master:
      pattern: '%date{"yyyy-MM-dd''T''HH:mm:ss,SSSXXX", UTC} [system] [%t] %-5level %logger{36} - %msg%n'
      rootLoglevel: info
      loggers:
        io.axual: info
        io.confluent: info
        org.apache.kafka.clients.admin.AdminClientConfig: info
        org.apache.kafka.clients.producer.ProducerConfig: info
        org.apache.kafka.clients.consumer.ConsumerConfig: info
    slave:
      pattern: '%date{"yyyy-MM-dd''T''HH:mm:ss,SSSXXX", UTC} [system] [%t] %-5level %logger{36} - %msg%n'
      rootLoglevel: info
      loggers:
        io.axual: info
        io.confluent: info
        org.apache.kafka.clients.admin.AdminClientConfig: info
        org.apache.kafka.clients.producer.ProducerConfig: info
        org.apache.kafka.clients.consumer.ConsumerConfig: info

Ingress configuration

Ingress configuration is responsible for exposing the services externally. By default, the slave ingress only gets exposed. Master is recommended to be disabled since write access should be restricted to the management API.

Here is an example on how you can configure it.

values.yaml

axual-schema-registry:

  ingress:
    slave:
      # -- Enable creation of the Ingress resource to expose this service.
      enabled: true
      # -- The name of the IngressClass cluster resource.
      # The associated IngressClass defines which controller will implement the resource.
      className: "nginx"
      hosts:
        - # -- The fully qualified domain name of a network host.
          host: "platform.local"
          paths:
            - # -- Matched against the path of an incoming request.
              path: "/"
              # -- Determines the interpretation of the Path matching.
              # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
              pathType: "ImplementationSpecific"
      tls: []
    master:
      # -- Enable creation of the Ingress resource to expose this service.
      enabled: false
      # -- The name of the IngressClass cluster resource.
      # The associated IngressClass defines which controller will implement the resource.
      className: "nginx"
      hosts:
        - # -- The fully qualified domain name of a network host.
          host: "platform.local"
          paths:
            - # -- Matched against the path of an incoming request.
              path: "/"
              # -- Determines the interpretation of the Path matching.
              # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
              pathType: "ImplementationSpecific"
      tls: []

Route Configuration

Axual Schema Registry helm-charts allow configuring an OpenShift Route to make it accessible outside the kubernetes cluster.

Here is an example on how you can configure it.

values.yaml

axual-schema-registry:

  route:
    slave:
      # -- Enable creation of an OpenShift Route resource to expose sr-slave.
      enabled: false
      # -- Annotations to add to the Route.
      annotations: {}
      # -- Labels to add to the route.
      labels: {}
      # -- An alias/DNS that points to the service. Optional. If not specified a route name will typically be automatically chosen.
      host: ""
      # -- subdomain is a DNS subdomain that is requested within the ingress controller’s domain (as a subdomain). If host is set this field is ignored.
      subdomain: ""
      # -- Path that the router watches for, to route traffic for to the service.
      path: "/api"
      tls:
        # -- The Certificate Authority certificate contents.
        caCertificate: ""
        # -- Certificate contents. This should be a single serving certificate, not a certificate chain. Do not include a CA certificate.
        certificate: ""
        # -- Key file contents.
        key: ""
        # -- Indicates termination type. One of: `edge`, `passthrough`, or `reencrypt`.
        termination: "passthrough"
        # --The CA certificate of the final destination. When using reencrypt termination this file should be provided
        # in order to have routers use it for health checks on the secure connection.
        # destinationCACertificate: ""
    master:
      # -- Enable creation of an OpenShift Route resource to expose master.
      enabled: false
      # -- Annotations to add to the Route.
      annotations: {}
      # -- Labels to add to the route.
      labels: {}
      # -- An alias/DNS that points to the service. Optional. If not specified a route name will typically be automatically chosen.
      host: ""
      # -- subdomain is a DNS subdomain that is requested within the ingress controller’s domain (as a subdomain). If host is set this field is ignored.
      subdomain: ""
      # -- Path that the router watches for, to route traffic for to the service.
      path: "/api"
      tls:
        # -- The Certificate Authority certificate contents.
        caCertificate: ""
        # -- Certificate contents. This should be a single serving certificate, not a certificate chain. Do not include a CA certificate.
        certificate: ""
        # -- Key file contents.
        key: ""
        # -- Indicates termination type. One of: `edge`, `passthrough`, or `reencrypt`.
        termination: "passthrough"
        # --The CA certificate of the final destination. When using reencrypt termination this file should be provided
        # in order to have routers use it for health checks on the secure connection.
        # destinationCACertificate: ""