Configure Apicurio

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

About Apicurio Registry

Apicurio Registry is a runtime server system that stores a specific set of artifacts as files. Apicurio Registry enables you to add, update, and remove the artifacts from the store using a REST API.

Apicurio Configuration

When configuring Apicurio 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 Apicurio Documentation.

Apicurio Registry image Configuration

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

You can configure it in the following way:

values.yaml

apicurio-registry:

  image:
    registry: "docker.axual.io"
    repository: "axual/apicurio-registry-kafkasql"
    tag: "2.3.1"
    pullPolicy: "Always"
  imagePullSecrets:
    - name: docker-credentials

Kafka init container

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

The apicurioPrincipal is the principal common name identifying the client-certificate used by Apicurio Registry to produce and consume from schemas topic. We might need to use the SSL chain to identify the principal or the CN, depending on how the Kafka installation is configured
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

apicurio-registry:

  kafkaInitContainer:
    apicurioPrincipal: "[0] CN=Dummy Root, [1] CN=Dummy Intermediate, [2] CN=Apicurio Registry"
    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 Apicurio Registry and the Kafka cluster. These configurations are used by both the Kafka init container and the Apicurio 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 Apicurio Registry container.
The schemasTopic is the fully resolved name of the topic used to store schemas (typically _{tenant}-{instance}-apicurio-schemas)
The groupPatternPrefix is the group prefix to give access to (typically {tenant}-{instance}-apicurio)

Here is an example:

values.yaml

apicurio-registry:

  kafka:
    bootstrapServers: "kafka-bootstrap:9093"
    schemasTopic: "_tenant-instance-apicurio-schemas"
    groupPatternPrefix: "{tenant}-{instance}-apicurio)"

TLS Configuration

When using TLS, you will need to specify secrets containing the PEM certificates for keystore generation:

Server keypair
Client keypair
Truststore

values.yaml

apicurio-registry:

  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 secrets.

Application Configuration

Apicurio Registry is a Quarkus application. In a Quarkus application, you can define various configuration properties in the application.properties files. What is present under config in the yml file, gets injected in a ConfigMap and mounted as an application.properties file.

The configuration options allow you to fine-tune the behavior of the Apicurio Registry. You can customize the configurations according to your requirements, as shown in the example below.

values.yaml

apicurio-registry:

  config:
    # Quarkus settings
    quarkus.http.ssl.client.auth: REQUEST
    # Logging level
    registry.loglevel: DEBUG
    # UI config
    registry.ui.config.apiurl: https://platform.local/apis/registry
    registry.ui.config.uiurl: https://platform.local/ui

    # Auth settings
    auth.enabled: "true"
    client.credentials.basic.auth.enabled: "true"
    role.based.auth.enabled: "true"

    # Apicurio Keycloak related configs
    registry.auth.type: oidc
    keycloak.url: https://platform.local/auth
    registry.auth.url.configured: https://platform.local/auth/realms/apicurio
    keycloak.realm: apicurio
    keycloak.api.client.id: apicurio-api
    keycloak.ui.client.id: apicurio-web
    registry.oidc.ui.redirect.url: https://platform.local/ui
    registry.oidc.ui.client.id: apicurio-web
    registry.auth.anonymous.read.access.enabled: "true"

Changing Authentication mechanism and permissions

Out-of-the-box Apicurio supports different settings for Authentication - see more in official documentation.

Ingress Configuration

Ingress configuration is responsible for exposing the service externally.

Here is an example on how you can configure it.

values.yaml

apicurio-registry:

  ingress:
    # -- 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: []

Keycloak Configuration

Apicurio chart initiates with the additional installation of Keycloak, which starts in a separate pod. For detailed information needed to configure Keycloak in apicurio-registry.keycloak section, please refer to the Instruction.

You can configure the Keycloak settings to align with your existing installation, as shown in the example below.

values.yaml

apicurio-registry:

  keycloak:
    enabled: true
    args: [ 'start-dev' ]
    autoscaling:
      enabled: false
    database:
      vendor: "mysql"
      hostname: "kc-mysql"
      database: "keycloak-db"
      port: "3306"
      username: "keycloak"
      password: "Passw0rd1!"
    extraVolumes: |
      - name: realm-config
        configMap:
          name: axual-streaming-apicurio-registry-keycloak-realm
      - name: keycloak-certs
        secret:
          secretName: platform-local-tls
    extraVolumeMounts: |
      - name: realm-config
        mountPath: "/realm-config"
        readOnly: true
      - name: keycloak-certs
        mountPath: "/keycloak-certs"
        readOnly: true
    extraEnv: |
      - name: KEYCLOAK_ADMIN
        value: "admin"
      - name: KEYCLOAK_ADMIN_PASSWORD
        value: "admin123"
      - name: JAVA_OPTS_APPEND
        value: -Djgroups.dns.query={{ template "keycloak.serviceDnsName" . }}
      - name: KC_HTTP_ENABLED
        value: "true"
      - name: KC_FEATURES
        value: "preview"
      - name: KC_HOSTNAME_STRICT
        value: "false"
      - name: KEYCLOAK_IMPORT
        value: /realm-config/realm.json
      - name: KC_HTTPS_CERTIFICATE_FILE
        value: /keycloak-certs/tls.crt
      - name: KC_HTTPS_CERTIFICATE_KEY_FILE
        value: /keycloak-certs/tls.key
    ingress:
      annotations:
        "nginx.ingress.kubernetes.io/client-body-buffer-size": 5M
      enabled: true
      className: "nginx"
      rules:
        - # -- The fully qualified domain name of a network host.
          host: "platform.local"
          paths:
            - # -- Matched against the path of an incoming request.
              path: "/auth"
              # -- Determines the interpretation of the Path matching.
              # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
              pathType: "ImplementationSpecific"
      tls:
        - hosts:
            - "platform.local"
          # Require the presence of this certificate in ur k8s cluster
          secretName: "platform-local-tls"
      clientCertificatePem: <client certificate chain>
      clientKeyPem: <client private key>

MySQL datastore Configuration for Keycloak

To configure the Keycloak server to store data in a MySQL database, you need to provide the database configuration.

Here is an example of how you can configure the mysql for Keycloak.

values.yaml

apicurio-registry:

  keycloak-mysql:
    enabled: true
    fullnameOverride: "kc-mysql"
    auth:
      rootPassword: "rootpassword"
      database: "keycloak-db"
      username: "keycloak"
      password: "Passw0rd1!"

Disabling Keycloak

If you want to use external pre-existing Keycloak installation, you can turn off deployment of Keycloak that comes with this chart by setting variable apicurio-registry.keycloak.enabled and apicurio-registry.keycloak-mysql.enabled to false in the Chart.yaml.

Properties under apicurio-registry.keycloak and apicurio-registry.config.keycloak should be adjusted accordingly to your existing installation.