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 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: "registry.axual.io"
    repository: "axual/apicurio-registry-kafkasql"
    tag: "2.6.8"
    pullPolicy: "Always"
  imagePullSecrets:
    - name: [your-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 and configurations (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-server]:[kafka-boostrap-server-port]"
    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

To enable Basic Authentication, ensure that Apicurio’s truststore contains the required Certificate Authority (CA) for Keycloak.

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.

Boolean values need to be wrapped between double-quotes to be properly translated into the 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:
    registry.ccompat.use-canonical-hash: "true"
    registry.ccompat.legacy-id-mode.enabled: "false"
    registry.ui.config.auth.type: "oidc"
    registry.auth.anonymous-read-access.enabled: "true"
    registry.auth.role-based-authorization: "true"

Changing Authentication mechanism and permissions

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

By default, we have configured Apicurio to run without authentication. Any anonymous user can create, view, and delete artifacts.

values.yaml

apicurio-registry:

  apicurioKeycloakMysql:
    enabled: false

  apicurioKeycloak:
    enabled: false

For production installation we advise to

Enable RBAC Authentication
Enable HTTP Basic Authentication
Enable Anonymous read-only access

Production Authentication Configuration

To enable Apicurio’s Authentication, you will need to have a running Keycloak properly configured with realm, clients, and users.

As part of our Apicurio Helm Charts, we provide Keycloak and MySQL.

Enable MySQL datastore 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:

  apicurioKeycloakMysql:
    enabled: true
    fullnameOverride: "apicurio-kc-mysql"
    auth:
      rootPassword: "[root-password]"
      database: "[keycloak-db-name]"
      username: "[keycloak-db-username]"
      password: "[keycloak-db-password]"

Since we are using the Bitnami MySQL helm charts, we suggest looking at the MySQL public documentation to have a complete list of configurations.

Enable Keycloak

Once you have configured the Keycloak MySQL, you can configure the Keycloak to import the Apicurio realm provided in the Streaming Charts.

Here is an example of how you can configure the Keycloak to enable Apicurio Authentication.

values.yaml

apicurio-registry:

  apicurioKeycloak:
    # -- Required when running Apicurio Keycloak on the same k8s cluster as Governance Keycloak
    nameOverride: "apicurio-keycloak"
    enabled: true
    # -- By default, we are importing the Apicurio realm used to Authenticate Admin access
    args: [ 'start', '--import-realm' ]
    realm: "apicurio"
    autoscaling:
      enabled: false
    database:
      vendor: "mysql"
      hostname: "apicurio-kc-mysql"
      database: "[keycloak-db-name]"
      port: "3306"
      username: "[keycloak-db-username]"
      password: "[keycloak-db-password]"

      extraVolumes: |
        - name: keycloak-init-realm
          configMap:
            name: "[apicurio-full-name]-keycloak-realm"

      extraVolumeMounts: |
        - name: keycloak-init-realm
          mountPath: "/opt/keycloak/data/import"
          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_HOSTNAME_STRICT
          value: "false"

    ingress:
      enabled: true
      className: "nginx"
      rules:
        - # -- The fully qualified domain name of a network host.
          host: "[apicurio-keycloak-host]"
          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: [ ]

Since we are using the Codecentric KeycloakX helm charts, we suggest looking at the KeycloakX public documentation to have a complete list of configurations.

Enable Apicurio Authentication

Once you have configured the Keycloak MySQL and Keycloak, you can now configure the Apicurio to interact with the Keycloak to perform Authentication.

Here is an example of how you can configure the Apicurio Authentication.

values.yaml

apicurio-registry:

  # The configuration related to authentication and authorization of users to the registry
  # Note: In order for any other authentication feature to work,
  # security.authentication.enabled needs to be enabled
  security:
    authentication:
      enabled: true
      basicAuthEnabled: true

      # Attributes that are required for Apicurio to access the Keycloak instance
      # in case the security.authentication.enabled is enabled and
      # security.authentication.basicAuthEnabled is enabled
      keycloak:
        authUrl: "https://[apicurio-keycloak-host]/auth"
        realm: "apicurio"
        webClientId: "apicurio-web"
        webRedirectUrl: "https://[apicurio-host]/ui"