Apicurio Studio

Configuring your Apicurio Registry deployment

This chapter explains various configuration options for Apicurio Registry, such as authentication settings, logging, and health checks on OpenShift.

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.

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 Strimzi or PostgreSQL.

Procedure
  1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

  2. Click Installed Operators > Apicurio Registry.

  3. On the ApicurioRegistry tab, click the Operator custom resource for your deployment, for example, example-apicurioregistry.

  4. In the main overview page, find the Deployment Name section and the corresponding DeploymentConfig name for your Apicurio Registry deployment, for example, example-apicurioregistry.

  5. In the left navigation menu, click Workloads > Deployment Configs, and select your DeploymentConfig name.

  6. Click the Environment tab, and enter your environment variables in the Single values env section, for example:

    • NAME: LIVENESS_STATUS_RESET

    • VALUE: 350

  7. Click Save at the bottom.

    Alternatively, you can perform these steps using the OpenShift oc command. For more details, see the OpenShift CLI documentation.

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 Configuring Apicurio Registry health checks on OpenShift.

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

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

Apicurio Registry authentication and authorization configuration options

This section describes the authentication and authorization options for Apicurio Registry using Keycloak.

You can enable authentication for the Apicurio Registry web console and core REST API using Keycloak. The same Keycloak realm and users are federated across the Apicurio Registry web console and core REST API using Open ID Connect (OIDC) so that you only require one set of credentials.

Apicurio Registry supports a number of authorization configurations, including role-based and content-based approaches. Apicurio Registry provides role-based authorization for default admin, write, and read-only user roles. Apicurio Registry also provides content-based authorization at the schema or API level, where only the creator of the registry artifact can update or delete it. Apicurio Registry authentication and authorization options are disabled by default.

Prerequisites
  • Keycloak is installed and running, and configured with a Keycloak realm and a user. For more details, see Getting Started with Keycloak.

  • Apicurio Registry is installed and running.

Apicurio Registry authentication using Keycloak

You can set the following environment variables to configure authentication for the Apicurio Registry web console and API using Keycloak:

Table 3. Configuration for Apicurio Registry authentication options
Environment variable Description Type Default

AUTH_ENABLED

Enables/disables authentication in registry. When set to true, the environment variables that follow are required.

String

false

KEYCLOAK_URL

The URL of the Keycloak authentication server to use. Must end with /auth.

String

-

KEYCLOAK_REALM

The Keycloak realm used for authentication.

String

-

KEYCLOAK_API_CLIENT_ID

The client ID for the Apicurio Registry REST API.

String

registry-api

KEYCLOAK_UI_CLIENT_ID

The client ID for the Apicurio Registry web console.

String

apicurio-registry

By default, Apicurio Registry supports authentication using the OpenID Connect protocol. This means that users (or API clients) must obtain an access token to make authenticated calls to the Apicurio Registry REST API. However, because some tools do not support OpenID Connect, you can also configure Apicurio Registry to support HTTP basic authentication by setting the following configuration property to true:
Table 4. Configuration for Apicurio Registry to enable BASIC authentication support
Environment variable Java system property Type Default value

CLIENT_CREDENTIALS_BASIC_AUTH_ENABLED

registry.auth.basic-auth-client-credentials.enabled

Boolean

false

Role-based authorization in Apicurio Registry

Set the following option to true to enable role-based authorization in Apicurio Registry:

Table 5. Configuration for Apicurio Registry role-based authorization
Environment variable Java system property Type Default value

ROLE_BASED_AUTHZ_ENABLED

registry.auth.role-based-authorization

Boolean

false

You can configure role-based authorization to use roles found in the user’s authentication token (for example, granted when authenticating using Keycloak), or to use role mappings managed internally by Apicurio Registry.

Using roles from Keycloak

To enable using roles assigned by Keycloak set the following environment variables:

Table 6. Configuration for Apicurio Registry role-based authorization using Keycloak
Environment variable Description Type Default

ROLE_BASED_AUTHZ_SOURCE

When set to token, user roles will be taken from the auth token.

String

token

REGISTRY_AUTH_ROLES_ADMIN

The name of the role that indicates a user is an Admin.

String

sr-admin

REGISTRY_AUTH_ROLES_DEVELOPER

The name of the role that indicates a user is a Developer.

String

sr-developer

REGISTRY_AUTH_ROLES_READONLY

The name of the role that indicates a user has Read Only access.

String

sr-readonly

When Apicurio Registry is configured to use roles from Keycloak, you must assign Apicurio Registry users to at least one of the following user roles in Keycloak (note that the role names are configurable via the environment variables defined in the table above):

Table 7. Apicurio Registry roles for authentication and authorization
Role Read artifacts Write artifacts Global rules Description

sr-admin

Yes

Yes

Yes

Full access to all create, read, update, and delete operations.

sr-developer

Yes

Yes

No

Access to create, read, update, and delete operations, except configuring global rules and import/export. This role can configure artifact rules only.

sr-readonly

Yes

No

No

Access to read and search operations only. This role cannot configure any rules.

Managing roles directly in Apicurio Registry

To enable using roles managed internally by Apicurio Registry, set the following environment variables:

Table 8. Configuration for Apicurio Registry role-based authorization using internal role mappings
Environment variable Description Type Default

ROLE_BASED_AUTHZ_SOURCE

When set to application, user roles will be managed internally.

String

token

When using internally managed role mappings, users can be assigned a role using the /admin/roleMappings endpoint in the Apicurio Registry REST API. See the REST API documentation for details on how to use that API. Users can be granted exactly one role: ADMIN, DEVELOPER, or READ_ONLY. Only users with Admin privileges can grant access to other users. Because there are no default Admin users in Apicurio Registry, it is usually helpful to configure another way for users to be identified as admins. This admin-override configuration can be controlled with the following environment variables:

Table 9. Configuration for Apicurio Registry admin-override functionality
Environment variable Description Type Default

REGISTRY_AUTH_ADMIN_OVERRIDE_ENABLED

Enables the admin-override feature.

String

false

REGISTRY_AUTH_ADMIN_OVERRIDE_FROM

Where to look for admin-override information. Only token is currently supported.

String

token

REGISTRY_AUTH_ADMIN_OVERRIDE_TYPE

The type of information used to determine if a user is an admin. Values depend on the value of the FROM variable, for example, role or claim when FROM is token.

String

role

REGISTRY_AUTH_ADMIN_OVERRIDE_ROLE

The name of the role that indicates a user is an Admin.

String

sr-admin

REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM

The name of a JWT token claim to use for determining admin-override.

String

org-admin

REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM-VALUE

The value that the JWT token claim indicated by the CLAIM variable must be for the user to be granted admin-override.

String

true

For example, you can use the admin-override feature to assign the sr-admin role to a single user in Keycloak, which grants that user the admin role. That user can then use the /admin/roleMappings REST API (or associated UI) to grant roles to additional users (including additional admins).

Apicurio Registry artifact owner-only authorization option

Set the following option to true to enable owner-only authorization for updates to schema and API artifacts in Apicurio Registry:

Table 10. Configuration for owner-only authorization
Environment variable Java system property Type Default value

OWNER_ONLY_AUTHZ_ENABLED

registry.auth.owner-only-authorization

Boolean

false

Enabling owner-only authorization results in a configuration where users with write access can only modify content that they themselves created. So users will not be able to update or delete artifacts created by other users.

Additional Apicurio Registry authorization options

In addition to the two main types of authorization (role-based and owner-based authorization), Apicurio Registry supports the following authorization related features.

Anonymous read-only access

To enable anonymous users (REST API calls with no authentication credentials provided) to be allowed to make read-only calls to the REST API, the following option must be set to true:

Table 11. Configuration for anonymous read-only access
Environment variable Java system property Type Default value

REGISTRY_AUTH_ANONYMOUS-READ-ACCESS_ENABLED

registry.auth.anonymous-read-access.enabled

Boolean

false

Additional resources

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.

Checking the current log level for a specific logger

  • Use this curl command to obtain the current log level for the logger io.apicurio.registry.storage:

$ 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"}

Changing the log level for a specific logger

  • Use this curl command to change the log level for the logger io.apicurio.registry.storage to DEBUG:

$ 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"}

Reverting to the default log level

You can revert to the default log level the configuration of a specific logger. Use this curl command to change the log level for the logger io.apicurio.registry.storage to its default value:

$ 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"}