Chapter 6. Configuring and managing Apicurio Registry deployments This chapter explains how to configure and manage optional settings for your Apicurio Registry deployment on OpenShift: Section 6.1, "Configuring Apicurio Registry health checks on OpenShift" Section 6.2, "Environment variables for Apicurio Registry health checks" Section 6.3, "Managing Apicurio Registry environment variables" Section 6.4, "Configuring Apicurio Registry deployment using PodTemplate" Section 6.5, "Configuring the Apicurio Registry web console" Section 6.6, "Configuring Apicurio Registry logging" Section 6.7, "Configuring Apicurio Registry event sourcing" 6.1. Configuring Apicurio Registry health checks on OpenShift You can configure optional environment variables for liveness and readiness probes to monitor the health of the Apicurio Registry server on OpenShift: Liveness probes test if the application can make progress. If the application cannot make progress, OpenShift automatically restarts the failing Pod. Readiness probes test if the application is ready to process requests. If the application is not ready, it can become overwhelmed by requests, and OpenShift stops sending requests for the time that the probe fails. If other Pods are OK, they continue to receive requests. Important The default values of the liveness and readiness environment variables are designed for most cases and should only be changed if required by your environment. Any changes to the defaults depend on your hardware, network, and amount of data stored. These values should be kept as low as possible to avoid unnecessary overhead. Prerequisites You must have an OpenShift cluster with cluster administrator access. You must have already installed Apicurio Registry on OpenShift. You must have already installed and configured your chosen Apicurio Registry storage in AMQ Streams or PostgreSQL. Procedure In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges. Click Installed Operators > Red Hat Integration - Service Registry Operator . On the ApicurioRegistry tab, click the Operator custom resource for your deployment, for example, example-apicurioregistry . In the main overview page, find the Deployment Name section and the corresponding DeploymentConfig name for your Apicurio Registry deployment, for example, example-apicurioregistry . In the left navigation menu, click Workloads > Deployment Configs , and select your DeploymentConfig name. Click the Environment tab, and enter your environment variables in the Single values env section, for example: NAME : LIVENESS_STATUS_RESET VALUE : 350 Click Save at the bottom. Alternatively, you can perform these steps using the OpenShift oc command. For more details, see the OpenShift CLI documentation . Additional resources Section 6.2, "Environment variables for Apicurio Registry health checks" OpenShift documentation on monitoring application health 6.2. Environment variables for Apicurio Registry health checks This section describes the available environment variables for Apicurio Registry health checks on OpenShift. These include liveness and readiness probes to monitor the health of the Apicurio Registry server on OpenShift. For an example procedure, see Section 6.1, "Configuring Apicurio Registry health checks on OpenShift" . Important The following environment variables are provided for reference only. The default values are designed for most cases and should only be changed if required by your environment. Any changes to the defaults depend on your hardware, network, and amount of data stored. These values should be kept as low as possible to avoid unnecessary overhead. Liveness environment variables Table 6.1. Environment variables for Apicurio Registry liveness probes Name Description Type Default LIVENESS_ERROR_THRESHOLD Number of liveness issues or errors that can occur before the liveness probe fails. Integer 1 LIVENESS_COUNTER_RESET Period in which the threshold number of errors must occur. For example, if this value is 60 and the threshold is 1, the check fails after two errors occur in 1 minute Seconds 60 LIVENESS_STATUS_RESET Number of seconds that must elapse without any more errors for the liveness probe to reset to OK status. Seconds 300 LIVENESS_ERRORS_IGNORED Comma-separated list of ignored liveness exceptions. String io.grpc.StatusRuntimeException,org.apache.kafka.streams.errors.InvalidStateStoreException Note Because OpenShift automatically restarts a Pod that fails a liveness check, the liveness settings, unlike readiness settings, do not directly affect behavior of Apicurio Registry on OpenShift. Readiness environment variables Table 6.2. Environment variables for Apicurio Registry readiness probes Name Description Type Default READINESS_ERROR_THRESHOLD Number of readiness issues or errors that can occur before the readiness probe fails. Integer 1 READINESS_COUNTER_RESET Period in which the threshold number of errors must occur. For example, if this value is 60 and the threshold is 1, the check fails after two errors occur in 1 minute. Seconds 60 READINESS_STATUS_RESET Number of seconds that must elapse without any more errors for the liveness probe to reset to OK status. In this case, this means how long the Pod stays not ready, until it returns to normal operation. Seconds 300 READINESS_TIMEOUT Readiness tracks the timeout of two operations: How long it takes for storage requests to complete How long it takes for HTTP REST API requests to return a response If these operations take more time than the configured timeout, this is counted as a readiness issue or error. This value controls the timeouts for both operations. Seconds 5 Additional resources Section 6.1, "Configuring Apicurio Registry health checks on OpenShift" OpenShift documentation on monitoring application health 6.3. Managing Apicurio Registry environment variables Apicurio Registry Operator manages most common Apicurio Registry configuration, but there are some options that it does not support yet. If a high-level configuration option is not available in the ApicurioRegistry CR, you can use an environment variable to adjust it. You can update these by setting an environment variable directly in the ApicurioRegistry CR, in the spec.configuration.env field. These are then forwarded to the Deployment resource of Apicurio Registry. Procedure You can manage Apicurio Registry environment variables by using the OpenShift web console or CLI. OpenShift web console Select the Installed Operators tab, and then Red Hat Integration - Service Registry Operator . On the Apicurio Registry tab, click the ApicurioRegistry CR for your Apicurio Registry deployment. Click the YAML tab and then edit the spec.configuration.env section as needed. The following example shows how to set default global content rules: apiVersion: registry.apicur.io/v1 kind: ApicurioRegistry metadata: name: example-apicurioregistry spec: configuration: # ... env: - name: REGISTRY_RULES_GLOBAL_VALIDITY value: FULL # One of: NONE, SYNTAX_ONLY, FULL - name: REGISTRY_RULES_GLOBAL_COMPATIBILITY value: FULL # One of: NONE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE OpenShift CLI Select the project where Apicurio Registry is installed. Run oc get apicurioregistry to get the list of ApicurioRegistry CRs Run oc edit apicurioregistry on the CR representing the Apicurio Registry instance that you want to configure. Add or modify the environment variable in the spec.configuration.env section. The Apicurio Registry Operator might attempt to set an environment variable that is already explicitly specified in the spec.configuration.env field. If an environment variable configuration has a conflicting value, the value set by Apicurio Registry Operator takes precedence. You can avoid this conflict by either using the high-level configuration for the feature, or only using the explicitly specified environment variables. The following is an example of a conflicting configuration: apiVersion: registry.apicur.io/v1 kind: ApicurioRegistry metadata: name: example-apicurioregistry spec: configuration: # ... ui: readOnly: true env: - name: REGISTRY_UI_FEATURES_READONLY value: false This configuration results in the Apicurio Registry web console being in read-only mode. 6.4. Configuring Apicurio Registry deployment using PodTemplate Important This is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview . The ApicurioRegistry CRD contains the spec.deployment.podTemplateSpecPreview field, which has the same structure as the field spec.template in a Kubernetes Deployment resource (the PodTemplateSpec struct). With some restrictions, the Apicurio Registry Operator forwards the data from this field to the corresponding field in the Apicurio Registry deployment. This provides greater configuration flexibility, without the need for the Apicurio Registry Operator to natively support each use case. The following table contains a list of subfields that are not accepted by the Apicurio Registry Operator, and result in a configuration error: Table 6.3. Restrictions on the podTemplateSpecPreview subfields podTemplateSpecPreview subfield Status Details metadata.annotations alternative exists spec.deployment.metadata.annotations metadata.labels alternative exists spec.deployment.metadata.labels spec.affinity alternative exists spec.deployment.affinity spec.containers[*] warning To configure the Apicurio Registry container, name: registry must be used spec.containers[name = "registry"].env alternative exists spec.configuration.env spec.containers[name = "registry"].image reserved - spec.imagePullSecrets alternative exists spec.deployment.imagePullSecrets spec.tolerations alternative exists spec.deployment.tolerations Warning If you set a field in podTemplateSpecPreview , its value must be valid, as if you configured it in the Apicurio Registry Deployment directly. The Apicurio Registry Operator might still modify the values you provided, but it will not fix an invalid value or make sure a default value is present. Additional resources Kubernetes documentation on Pod templates 6.5. Configuring the Apicurio Registry web console You can set optional environment variables to configure the Apicurio Registry web console specifically for your deployment environment or to customize its behavior. Prerequisites You have already installed Apicurio Registry. Configuring the web console deployment environment When you access the Apicurio Registry web console in your browser, some initial configuration settings are loaded. The following configuration settings are important: URL for core Apicurio Registry server REST API URL for Apicurio Registry web console client Typically, Apicurio Registry automatically detects and generates these settings, but there are some deployment environments where this automatic detection can fail. If this happens, you can configure environment variables to explicitly set these URLs for your environment. Procedure Configure the following environment variables to override the default URLs: REGISTRY_UI_CONFIG_APIURL : Specifies the URL for the core Apicurio Registry server REST API. For example, https://registry.my-domain.com/apis/registry REGISTRY_UI_CONFIG_UIURL : Specifies the URL for the Apicurio Registry web console client. For example, https://registry.my-domain.com/ui Configuring the web console in read-only mode You can configure the Apicurio Registry web console in read-only mode as an optional feature. This mode disables all features in the Apicurio Registry web console that allow users to make changes to registered artifacts. For example, this includes the following: Creating an artifact Uploading a new artifact version Updating artifact metadata Deleting an artifact Procedure Configure the following environment variable: REGISTRY_UI_FEATURES_READONLY : Set to true to enable read-only mode. Defaults to false . 6.6. Configuring Apicurio Registry logging You can set Apicurio Registry logging configuration at runtime. Apicurio Registry provides a REST endpoint to set the log level for specific loggers for finer grained logging. This section explains how to view and set Apicurio Registry log levels at runtime using the Apicurio Registry /admin REST API. Prerequisites Get the URL to access your Apicurio Registry instance, or get your Apicurio Registry route if you have Apicurio Registry deployed on OpenShift. This simple example uses a URL of localhost:8080 . Procedure Use this curl command to obtain the current log level for the logger io.apicurio.registry.storage : USD curl -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"INFO"} Use this curl command to change the log level for the logger io.apicurio.registry.storage to DEBUG : USD curl -X PUT -i -H "Content-Type: application/json" --data '{"level":"DEBUG"}' localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"DEBUG"} Use this curl command to revert the log level for the logger io.apicurio.registry.storage to its default value: USD curl -X DELETE -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"INFO"} 6.7. Configuring Apicurio Registry event sourcing Important This is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview . You can configure Apicurio Registry to send events when changes are made to registry content. For example, Apicurio Registry can trigger events when schema or API artifacts, groups, or content rules are created, updated, deleted, and so on. You can configure Apicurio Registry to send events to your applications and to third-party integrations for these kind of changes. There are different protocols available for transporting events. The currently implemented protocols are HTTP and Apache Kafka. However, regardless of the protocol, the events are sent by using the CNCF CloudEvents specification. You can configure Apicurio Registry event sourcing by using Java system properties or the equivalent environment variables. Apicurio Registry event types All of the event types are defined in io.apicurio.registry.events.dto.RegistryEventType . For example, these include the following event types: io.apicurio.registry.artifact-created io.apicurio.registry.artifact-updated io.apicurio.registry.artifact-state-changed io.apicurio.registry.artifact-rule-created io.apicurio.registry.global-rule-created io.apicurio.registry.group-created Prerequisites You must have an application that you want to send Apicurio Registry cloud events to. For example, this can be a custom application or a third-party application. Configuring Apicurio Registry event sourcing by using HTTP The example in this section shows a custom application running on http://my-app-host:8888/events . Procedure When using the HTTP protocol, set your Apicurio Registry configuration to send events to a your application as follows: registry.events.sink.my-custom-consumer=http://my-app-host:8888/events If required, you can configure multiple event consumers as follows: registry.events.sink.my-custom-consumer=http://my-app-host:8888/events registry.events.sink.other-consumer=http://my-consumer.com/events Configuring Apicurio Registry event sourcing by using Apache Kafka The example in this section shows a Kafka topic named my-registry-events running on my-kafka-host:9092 . Procedure When using the Kafka protocol, set your Kafka topic as follows: registry.events.kafka.topic=my-registry-events You can set the configuration for the Kafka producer by using the KAFKA_BOOTSTRAP_SERVERS environment variable: KAFKA_BOOTSTRAP_SERVERS=my-kafka-host:9092 Alternatively, you can set the properties for the kafka producer by using the registry.events.kafka.config prefix, for example: registry.events.kafka.config.bootstrap.servers=my-kafka-host:9092 If required, you can also set the Kafka topic partition to use to produce events: registry.events.kafka.topic-partition=1 Additional resources For more details, see the CNCF CloudEvents specification .

Commands:
apiVersion: registry.apicur.io/v1 kind: ApicurioRegistry metadata: name: example-apicurioregistry spec: configuration: # env: - name: REGISTRY_RULES_GLOBAL_VALIDITY value: FULL # One of: NONE, SYNTAX_ONLY, FULL - name: REGISTRY_RULES_GLOBAL_COMPATIBILITY value: FULL # One of: NONE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE
apiVersion: registry.apicur.io/v1 kind: ApicurioRegistry metadata: name: example-apicurioregistry spec: configuration: # ui: readOnly: true env: - name: REGISTRY_UI_FEATURES_READONLY value: false
curl -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"INFO"}
curl -X PUT -i -H "Content-Type: application/json" --data '{"level":"DEBUG"}' localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"DEBUG"}
curl -X DELETE -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage HTTP/1.1 200 OK [...] Content-Type: application/json {"name":"io.apicurio.registry.storage","level":"INFO"}