Apicurio Registry Operator configuration reference

This chapter provides detailed information on the custom resource used to configure the Apicurio Registry Operator to deploy Apicurio Registry:

Apicurio Registry Custom Resource
Apicurio Registry CR spec
Apicurio Registry CR status
Apicurio Registry managed resources
Apicurio Registry Operator labels

Apicurio Registry Custom Resource

The Apicurio Registry Operator defines an ApicurioRegistry custom resource (CR) that represents a single deployment of Apicurio Registry on OpenShift.

These resource objects are created and maintained by users to instruct the Apicurio Registry Operator how to deploy and configure Apicurio Registry.

Example ApicurioRegistry CR

The following command displays the ApicurioRegistry resource:

kubectl get apicurioregistry
kubectl edit apicurioregistry example-apicurioregistry

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
  namespace: demo-kafka
  # ...
spec:
  configuration:
    persistence: kafkasql
    kafkasql:
      bootstrapServers: 'my-cluster-kafka-bootstrap.demo-kafka.svc:9092'
  deployment:
    host: >-
      example-apicurioregistry.demo-kafka.example.com
status:
  conditions:
  - lastTransitionTime: "2021-05-03T10:47:11Z"
    message: ""
    reason: Reconciled
    status: "True"
    type: Ready
  info:
    host: example-apicurioregistry.demo-kafka.example.com
  managedResources:
  - kind: Deployment
    name: example-apicurioregistry-deployment
    namespace: demo-kafka
  - kind: Service
    name: example-apicurioregistry-service
    namespace: demo-kafka
  - kind: Ingress
    name: example-apicurioregistry-ingress
    namespace: demo-kafka

By default, the Apicurio Registry Operator watches its own project namespace only. Therefore, you must create the ApicurioRegistry CR in the same namespace, if you are deploying the Operator manually. You can modify this behavior by updating WATCH_NAMESPACE environment variable in the Operator Deployment resource.

Additional resources

Extending the Kubernetes API with Custom Resource Definitions

Apicurio Registry CR spec

The spec is the part of the ApicurioRegistry CR that is used to provide the desired state or configuration for the Operator to achieve.

ApicurioRegistry CR spec contents

The following example block contains the full tree of possible spec configuration options. Some fields might not be required or should not be defined at the same time.

spec:
  configuration:
    persistence: <string>
    sql:
      dataSource:
        url: <string>
        userName: <string>
        password: <string>
    kafkasql:
      bootstrapServers: <string>
      security:
        tls:
          truststoreSecretName: <string>
          keystoreSecretName: <string>
        scram:
          mechanism: <string>
          truststoreSecretName: <string>
          user: <string>
          passwordSecretName: <string>
    ui:
      readOnly: <string>
    logLevel: <string>
    registryLogLevel: <string>
    security:
      keycloak:
        url: <string>
        realm: <string>
        apiClientId: <string>
        uiClientId: <string>
      https:
        disableHttp: <bool>
        secretName: <string>
    env: <k8s.io/api/core/v1 []EnvVar>
  deployment:
    replicas: <int32>
    host: <string>
    affinity: <k8s.io/api/core/v1 Affinity>
    tolerations: <k8s.io/api/core/v1 []Toleration>
    imagePullSecrets: <k8s.io/api/core/v1 []LocalObjectReference>
    metadata:
      annotations: <map[string]string>
      labels: <map[string]string>
    image: <string>
    managedResources:
      disableIngress: <bool>
      disableNetworkPolicy: <bool>
	  disablePodDisruptionBudget: <bool>
    podTemplateSpecPreview: <k8s.io/api/core/v1 PodTemplateSpec>

The following table describes each configuration option:

Table 1. ApicurioRegistry CR spec configuration options
Configuration option	type	Default value	Description
`configuration`	-	-	Section for configuration of Apicurio Registry application
`configuration/persistence`	string	`mem`	Storage backend. One of `mem`, `sql`, `kafkasql`
`configuration/sql`	-	-	SQL storage backend configuration
`configuration/sql/dataSource`	-	-	Database connection configuration for SQL storage backend
`configuration/sql/dataSource/url`	string	required	Database connection URL string
`configuration/sql/dataSource/userName`	string	required	Database connection user
`configuration/sql/dataSource/password`	string	empty	Database connection password
`configuration/kafkasql`	-	-	Kafka storage backend configuration
`configuration/kafkasql/bootstrapServers`	string	required	Kafka bootstrap server URL, for Streams storage backend
`configuration/kafkasql/security/tls`	-	-	Section to configure TLS authentication for Kafka storage backend
`configuration/kafkasql/security/tls/truststoreSecretName`	string	required	Name of a secret containing TLS truststore for Kafka
`configuration/kafkasql/security/tls/keystoreSecretName`	string	required	Name of a secret containing user TLS keystore
`configuration/kafkasql/security/scram/truststoreSecretName`	string	required	Name of a secret containing TLS truststore for Kafka
`configuration/kafkasql/security/scram/user`	string	required	SCRAM user name
`configuration/kafkasql/security/scram/passwordSecretName`	string	required	Name of a secret containing SCRAM user password
`configuration/kafkasql/security/scram/mechanism`	string	`SCRAM-SHA-512`	SASL mechanism
`configuration/ui`	-	-	Apicurio Registry web console settings
`configuration/ui/readOnly`	string	`false`	Set Apicurio Registry web console to read-only mode
`configuration/logLevel`	string	`INFO`	Apicurio Registry log level, for non-Apicurio components and libraries. One of `INFO`, `DEBUG`
`configuration/registryLogLevel`	string	`INFO`	Apicurio Registry log level, for Apicurio application components (excludes non-Apicurio components and libraries). One of `INFO`, `DEBUG`
`configuration/security`	-	-	Apicurio Registry web console and REST API security settings
`configuration/security/keycloak`	-	-	Web console and REST API security configuration using Keycloak
`configuration/security/keycloak/url`	string	required	Keycloak URL
`configuration/security/keycloak/realm`	string	required	Keycloak realm
`configuration/security/keycloak/apiClientId`	string	`registry-client-api`	Keycloak client for REST API
`configuration/security/keycloak/uiClientId`	string	`registry-client-ui`	Keycloak client for web console
`configuration/security/https`	-	-	Configuration for HTTPS. For more details, see Configuring an HTTPS connection to Apicurio Registry from inside the OpenShift cluster.
`configuration/security/https/sercretName`	string	empty	Name of a Kubernetes Secret that contains the HTTPS certificate and key, which must be named `tls.crt` and `tls.key`, respectively. Setting this field enables HTTPS, and vice versa.
`configuration/security/https/disableHttp`	bool	`false`	Disable HTTP port and Ingress. HTTPS must be enabled as a prerequisite.
`configuration/env`	k8s.io/api/core/v1 []EnvVar	empty	Configure a list of environment variables to be provided to the Apicurio Registry pod. For more details, see Managing Apicurio Registry environment variables.
`deployment`	-	-	Section for Apicurio Registry deployment settings
`deployment/replicas`	positive integer	`1`	Number of Apicurio Registry pods to deploy
`deployment/host`	string	auto-generated	Host/URL where the Apicurio Registry console and API are available. If possible, Apicurio Registry Operator attempts to determine the correct value based on the settings of your cluster router. The value is auto-generated only once, so user can override it afterwards.
`deployment/affinity`	k8s.io/api/core/v1 Affinity	empty	Apicurio Registry deployment affinity configuration
`deployment/tolerations`	k8s.io/api/core/v1 []Toleration	empty	Apicurio Registry deployment tolerations configuration
`deployment/imagePullSecrets`	k8s.io/api/core/v1 []LocalObjectReference	empty	Configure image pull secrets for Apicurio Registry deployment
`deployment/metadata`	-	-	Configure a set of labels or annotations for the Apicurio Registry pod.
`deployment/metadata/labels`	map[string]string	empty	Configure a set of labels for Apicurio Registry pod
`deployment/metadata/annotations`	map[string]string	empty	Configure a set of annotations for Apicurio Registry pod
`deployment/image`	string	empty	Override the default image being used to deploy Apicurio Registry
`deployment/managedResources`	-	-	Section to configure how the Apicurio Registry Operator manages Kubernetes resources. For more details, see Apicurio Registry managed resources.
`deployment/managedResources/disableIngress`	bool	`false`	If set, the operator will not create and manage an `Ingress` resource for Apicurio Registry deployment.
`deployment/managedResources/disableNetworkPolicy`	bool	`false`	If set, the operator will not create and manage a `NetworkPolicy` resource for Apicurio Registry deployment.
`deployment/managedResources/disablePodDisruptionBudget`	bool	`false`	If set, the operator will not create and manage an `PodDisruptionBudget` resource for Apicurio Registry deployment.
`deployment/podTemplateSpecPreview`	k8s.io/api/core/v1 PodTemplateSpec	empty	Configure parts of the Apicurio Registry deployment resource. For more details, see Configuring Apicurio Registry deployment using PodTemplate.

If an option is marked as required, it might be conditional on other configuration options being enabled. Empty values might be accepted, but the Operator does not perform the specified action.

Apicurio Registry CR status

The status is the section of the CR managed by the Apicurio Registry Operator that contains a description of the current deployment and application state.

ApicurioRegistry CR status contents

The status section contains the following fields:

status:
  info:
    host: <string>
  conditions: <list of:>
  - type: <string>
    status: <string, one of: True, False, Unknown>
    reason: <string>
    message: <string>
    lastTransitionTime: <string, RFC-3339 timestamp>
  managedResources: <list of:>
  - kind: <string>
    namespace: <string>
    name: <string>

Table 2. ApicurioRegistry CR status fields
Status field	Type	Description
`info`	-	Section with information about the deployed Apicurio Registry.
`info/host`	string	URL where the Apicurio Registry UI and REST API are accessible.
`conditions`	-	List of conditions that report the status of the Apicurio Registry, or the Operator with respect to that deployment.
`conditions/type`	string	Type of the condition.
`conditions/status`	string	Status of the condition, one of `True`, `False`, `Unknown`.
`conditions/reason`	string	A programmatic identifier indicating the reason for the condition’s last transition.
`conditions/message`	string	A human-readable message indicating details about the transition.
`conditions/lastTransitionTime`	string	The last time the condition transitioned from one status to another.
`managedResources`	-	List of Kubernetes resources managed by Apicurio Registry Operator
`managedResources/kind`	string	Resource kind.
`managedResources/namespace`	string	Resource namespace.
`managedResources/name`	string	Resource name.

Apicurio Registry managed resources

The resources managed by the Apicurio Registry Operator when deploying Apicurio Registry are as follows:

Deployment
Ingress
NetworkPolicy
PodDisruptionBudget
Service

You can disable the Apicurio Registry Operator from creating and managing some resources, so they can be configured manually. This provides greater flexibility when using features that the Apicurio Registry Operator does not currently support.

If you disable a resource type, its existing instance is deleted. If you enable a resource, the Apicurio Registry Operator attempts to find a resource using the app label, for example, app=example-apicurioregistry, and starts managing it. Otherwise, the Operator creates a new instance.

You can disable the following resource types in this way:

Ingress
NetworkPolicy
PodDisruptionBudget

For example:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  deployment:
    managedResources:
      disableIngress: true
      disableNetworkPolicy: true
      disablePodDisruptionBudget: false # Can be omitted

Apicurio Registry Operator labels

Resources managed by the Apicurio Registry Operator are usually labeled as follows:

Table 3. Apicurio Registry Operator labels for managed resources
Label	Description
`app`	Name of the Apicurio Registry deployment that the resource belongs to, based on the name of the specified `ApicurioRegistry` CR.
`apicur.io/type`	Type of the deployment: `apicurio-registry` or `operator`
`apicur.io/name`	Name of the deployment: same value as `app` or `apicurio-registry-operator`
`apicur.io/version`	Version of the Apicurio Registry or the Apicurio Registry Operator
`app.kubernetes.io/*`	A set of recommended Kubernetes labels for application deployments.

Custom labels and annotations

You can provide custom labels and annotation for the Apicurio Registry pod, using the spec.deployment.metadata.labels and spec.deployment.metadata.annotations fields, for example:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    # ...
  deployment:
    metadata:
      labels:
        example.com/environment: staging
      annotations:
        example.com/owner: my-team

Additional resources

Recommended Kubernetes labels for application deployments