The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

マネジメントインターフェースリファレンス

デフォルトでは、QuarkusはメインHTTPサーバーの /q 以下に、 マネジメント エンドポイントを公開します。同じHTTPサーバーで、アプリケーションエンドポイントとマネジメントエンドポイントが提供されます。

本書では、マネジメントエンドポイントに別のHTTPサーバー(別のネットワークインターフェースとポートにバインド)を使用する方法について説明します。これにより、メインサーバー上でこれらのエンドポイントを公開することを避け、望ましくないアクセスを防止することができます。

1. マネジメントインターフェイスの有効化

マネジメントインタフェースを有効にするには、次の ビルド時 プロパティを使用します:

quarkus.management.enabled=true

デフォルトでは、管理エンドポイントは http://0.0.0.0:9000/q で公開されます。例えば、 smallrye-health をインストールしている場合、readiness probe は http://0.0.0.0:9000/q/health/ready で公開されます。

SmallRye Health Checks、SmallRye Metrics、Micrometer、Infoの各エンドポイントは、マネジメントインタフェースを有効にすると、マネジメントエンドポイントとして宣言されます。

管理インターフェースに依存するエクステンション(SmallRye HealthやSmallRye OpenAPIエクステンションなど)がインストールされていない場合、管理インターフェースは無効になります。

2. ホスト、ポート、スキームの設定

デフォルトでは、マネジメントインタフェースはインターフェース: 0.0.0.0 (すべてのインターフェース)およびポート: 9000 (テストモードでは 9001 )で公開されます。また、デフォルトではTLS( https )を使用しません。

ホスト、ポート、TLS証明書は、以下のプロパティを使用して設定できます:

  • quarkus.management.host - インターフェース/ホスト

  • quarkus.management.port - ポート

  • quarkus.management.test-port - テストモードで使用するポート

  • quarkus.management.ssl - メインのHTTPサーバーと同様 の、TLSの設定

ここでは、https://localhost:9002 で、マネジメントインタフェースを公開する設定例を示します:

quarkus.management.enabled=true
quarkus.management.host=localhost
quarkus.management.port=9002
quarkus.management.ssl.certificate.key-store-file=server-keystore.jks
quarkus.management.ssl.certificate.key-store-password=secret
メインのHTTPサーバーとは異なり、マネジメントインタフェースは http_と _https を同時に扱うことはありません。 https が設定されている場合、プレーンのHTTPリクエストは拒否されます。

3. ルートパスの設定

マネジメントエンドポイントは、標準的なHTTPエンドポイントとは異なる設定になっています。ユニークなルートパスを使用し、デフォルトでは /q になっています。このマネジメントルートパスは、 quarkus.management.root-path property を使用して設定することができます。例えば、マネジメントエンドポイントを /management の下に公開したい場合、 次を使用します:

quarkus.management.enabled=true
quarkus.management.root-path=/management

マネジメントエンドポイントのマウントルールは、メインのHTTPサーバーを使用する場合と若干異なります:

  • 相対 パス( / で始まらない)を使用して設定されたマネジメントエンドポイントは、設定されたルートパスから提供されます。例えば、エンドポイントのパスが health で、ルートパスが management の場合、結果として以下のようなパスになります。 /management/health

  • 絶対 パス( / で始まる)を使用して構成されたマネジメントエンドポイントは、ルートから提供されます。例えば、エンドポイントのパスが /health の場合、ルートパスに関係なく、結果として /health になります。

  • マネジメントインタフェースは、メインHTTPサーバーからのHTTPルートパスを使用しません。

quarkus.http.root-path プロパティは、メインの HTTP サーバーにのみ適用され、マネジメントインタフェースには適用されません。また、 quarkus.http.non-application-root-path プロパティは、マネジメントインタフェース上で公開されるエンドポイントには使用されません。

4. エクステンションでのマネジメントエンドポイントの作成

アプリケーションのコードからマネジメントインタフェースのエンドポイントを公開するには、 アプリケーションのセクション を参照してください。

SmallRye Health Checks、SmallRye Metrics、およびMicrometerの各エンドポイントは、マネジメントインタフェースが有効化されると、マネジメントエンドポイントとして宣言されます。

マネジメントインタフェースを有効にしない場合、これらのエンドポイントは、メインのHTTPサーバー(デフォルトでは /q 以下)を使用して提供されます。

エクステンションは、 アプリケーション以外の ルートを定義し、 management() メソッドを呼び出すことで、マネジメントエンドポイントを作成できます:

@BuildStep
void createManagementRoute(BuildProducer<RouteBuildItem> routes,
        NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
        MyRecorder recorder) {

    routes.produce(nonApplicationRootPathBuildItem.routeBuilder()
        .management() // Must be called BEFORE the routeFunction method
        .routeFunction("my-path", recorder.route())
        .handler(recorder.getHandler())
        .blockingRoute()
        .build());
    //...
}

マネジメントインタフェースが有効な場合、エンドポイントは http://0.0.0.0:9000/q/my-path で公開されます: 無効の場合は、 http://localhost:8080/q/my-path で公開されます。

マネジメントエンドポイントは、エクステンションによってのみ宣言でき、アプリケーションコードからは宣言できません。

5. (アプリケーションとして)マネジメントインタフェース上でエンドポイントを公開

マネジメントルーターにルートを登録することで、マネジメントインタフェースにエンドポイントを公開することができます。ルーターにアクセスするには、次のコードを使用します:

public void registerManagementRoutes(@Observes ManagementInterface mi) {
       mi.router().get("/admin").handler(rc ->
            rc.response().end("admin it is")
       );
}

io.quarkus.vertx.http.ManagementInterface イベントは、マネジメントインタフェースが初期化されたときに発生します。そのため、マネジメントインタフェースが有効になっていない場合は、このメソッドは呼び出されません。

router() メソッドは、ルートの登録に使用できる io.vertx.ext.web.Router オブジェクトを返します。ルートは、 / からの相対パスです。たとえば、前の例では、 /admin にルートを登録しています。デフォルトのホストとポートを使用する場合、このルートは http://0.0.0.0:9000/admin でアクセス可能です。

Router APIの詳細は、 Vert.x Webドキュメント に記載されています。

6. マネジメントインターフェイスの設定

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

タイプ

デフォルト

Enables / Disables the usage of a separate interface/port to expose the management endpoints. If sets to true, the management endpoints will be exposed to a different HTTP server. This avoids exposing the management endpoints on a publicly available server.

Environment variable: QUARKUS_MANAGEMENT_ENABLED

Show more

ブーリアン

false

If basic auth should be enabled.

Environment variable: QUARKUS_MANAGEMENT_AUTH_BASIC

Show more

ブーリアン

If this is true and credentials are present then a user will always be authenticated before the request progresses. If this is false then an attempt will only be made to authenticate the user if a permission check is performed or the current user is required for some other reason.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PROACTIVE

Show more

ブーリアン

true

Configures the engine to require/request client authentication. NONE, REQUEST, REQUIRED

Environment variable: QUARKUS_MANAGEMENT_SSL_CLIENT_AUTH

Show more

none, request, required

none

A common root path for management endpoints. Various extension-provided management endpoints such as metrics and health are deployed under this path by default.

Environment variable: QUARKUS_MANAGEMENT_ROOT_PATH

Show more

string

/q

If responses should be compressed.

Note that this will attempt to compress all responses, to avoid compressing already compressed content (such as images) you need to set the following header:

Content-Encoding: identity

Which will tell vert.x not to compress the response.

Environment variable: QUARKUS_MANAGEMENT_ENABLE_COMPRESSION

Show more

ブーリアン

false

When enabled, vert.x will decompress the request’s body if it’s compressed.

Note that the compression format (e.g., gzip) must be specified in the Content-Encoding header in the request.

Environment variable: QUARKUS_MANAGEMENT_ENABLE_DECOMPRESSION

Show more

ブーリアン

false

The compression level used when compression support is enabled.

Environment variable: QUARKUS_MANAGEMENT_COMPRESSION_LEVEL

Show more

int

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

タイプ

デフォルト

The HTTP port

Environment variable: QUARKUS_MANAGEMENT_PORT

Show more

int

9000

The HTTP port

Environment variable: QUARKUS_MANAGEMENT_TEST_PORT

Show more

int

9001

The HTTP host Defaults to 0.0.0.0 Defaulting to 0.0.0.0 makes it easier to deploy Quarkus to container, however it is not suitable for dev/test mode as other people on the network can connect to your development machine.

Environment variable: QUARKUS_MANAGEMENT_HOST

Show more

string

Enable listening to host:port

Environment variable: QUARKUS_MANAGEMENT_HOST_ENABLED

Show more

ブーリアン

true

The CredentialsProvider. If this property is configured, then a matching 'CredentialsProvider' will be used to get the keystore, keystore key, and truststore passwords unless these passwords have already been configured. Please note that using MicroProfile ConfigSource which is directly supported by Quarkus Configuration should be preferred unless using CredentialsProvider provides for some additional security and dynamism.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_CREDENTIALS_PROVIDER

Show more

string

The credentials provider bean name.

This is a bean name (as in @Named) of a bean that implements CredentialsProvider. It is used to select the credentials provider bean when multiple exist. This is unnecessary when there is only one credentials provider available.

For Vault, the credentials provider bean name is vault-credentials-provider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_CREDENTIALS_PROVIDER_NAME

Show more

string

The list of path to server certificates using the PEM format. Specifying multiple files requires SNI to be enabled.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_FILES

Show more

list of path

The list of path to server certificates private key files using the PEM format. Specifying multiple files requires SNI to be enabled. The order of the key files must match the order of the certificates.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_FILES

Show more

list of path

An optional key store that holds the certificate information instead of specifying separate files.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_FILE

Show more

path

An optional parameter to specify the type of the key store file. If not given, the type is automatically detected based on the file name.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_FILE_TYPE

Show more

string

An optional parameter to specify a provider of the key store file. If not given, the provider is automatically detected based on the key store file type.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PROVIDER

Show more

string

A parameter to specify the password of the key store file. If not given, and if it can not be retrieved from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PASSWORD

Show more

string

password

A parameter to specify a CredentialsProvider property key, which can be used to get the password of the key store file from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_PASSWORD_KEY

Show more

string

An optional parameter to select a specific key in the key store. When SNI is disabled, and the key store contains multiple keys and no alias is specified; the behavior is undefined.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_KEY_ALIAS

Show more

string

An optional parameter to define the password for the key, in case it is different from key-store-password If not given, it might be retrieved from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_KEY_PASSWORD

Show more

string

A parameter to specify a CredentialsProvider property key, which can be used to get the password for the key from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_KEY_STORE_KEY_PASSWORD_KEY

Show more

string

An optional trust store that holds the certificate information of the trusted certificates.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_FILE

Show more

path

An optional parameter to specify the type of the trust store file. If not given, the type is automatically detected based on the file name.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_FILE_TYPE

Show more

string

An optional parameter to specify a provider of the trust store file. If not given, the provider is automatically detected based on the trust store file type.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PROVIDER

Show more

string

A parameter to specify the password of the trust store file. If not given, it might be retrieved from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PASSWORD

Show more

string

A parameter to specify a CredentialsProvider property key, which can be used to get the password of the trust store file from CredentialsProvider.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_PASSWORD_KEY

Show more

string

An optional parameter to trust a single certificate from the trust store rather than trusting all certificates in the store.

Environment variable: QUARKUS_MANAGEMENT_SSL_CERTIFICATE_TRUST_STORE_CERT_ALIAS

Show more

string

The cipher suites to use. If none is given, a reasonable default is selected.

Environment variable: QUARKUS_MANAGEMENT_SSL_CIPHER_SUITES

Show more

list of string

Sets the ordered list of enabled SSL/TLS protocols.

If not set, it defaults to "TLSv1.3, TLSv1.2". The following list of protocols are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. To only enable TLSv1.3, set the value to to "TLSv1.3".

Note that setting an empty list, and enabling SSL/TLS is invalid. You must at least have one protocol.

Environment variable: QUARKUS_MANAGEMENT_SSL_PROTOCOLS

Show more

list of string

TLSv1.3,TLSv1.2

Enables Server Name Indication (SNI), an TLS extension allowing the server to use multiple certificates. The client indicate the server name during the TLS handshake, allowing the server to select the right certificate.

Environment variable: QUARKUS_MANAGEMENT_SSL_SNI

Show more

ブーリアン

false

When set to true, the HTTP server automatically sends 100 CONTINUE response when the request expects it (with the Expect: 100-Continue header).

Environment variable: QUARKUS_MANAGEMENT_HANDLE_100_CONTINUE_AUTOMATICALLY

Show more

ブーリアン

false

The maximum length of all headers.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE

Show more

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE

Show more

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE

Show more

MemorySize

8192

The maximum length of the initial line (e.g. "GET / HTTP/1.0").

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH

Show more

int

4096

The maximum length of a form attribute.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

Show more

MemorySize

2048

The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CONNECTIONS

Show more

int

Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting.

Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is 4,096 octets.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_HEADER_TABLE_SIZE

Show more

long

Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting.

Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CONCURRENT_STREAMS

Show more

long

Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is 2^14 (16,384) octets.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FRAME_SIZE

Show more

int

Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is 8192

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_LIST_SIZE

Show more

long

Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is 200, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

Show more

int

Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is 30 s, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_WINDOW_DURATION

Show more

Duration

Http connection idle timeout

Environment variable: QUARKUS_MANAGEMENT_IDLE_TIMEOUT

Show more

Duration

30M

Whether the files sent using multipart/form-data will be stored locally.

If true, they will be stored in quarkus.http.body-handler.uploads-directory and will be made available via io.vertx.ext.web.RoutingContext.fileUploads(). Otherwise, the files sent using multipart/form-data will not be stored locally, and io.vertx.ext.web.RoutingContext.fileUploads() will always return an empty collection. Note that even with this option being set to false, the multipart/form-data requests will be accepted.

Environment variable: QUARKUS_MANAGEMENT_BODY_HANDLE_FILE_UPLOADS

Show more

ブーリアン

true

The directory where the files sent using multipart/form-data should be stored.

Either an absolute path or a path relative to the current directory of the application process.

Environment variable: QUARKUS_MANAGEMENT_BODY_UPLOADS_DIRECTORY

Show more

string

${java.io.tmpdir}/uploads

Whether the form attributes should be added to the request parameters.

If true, the form attributes will be added to the request parameters; otherwise the form parameters will not be added to the request parameters

Environment variable: QUARKUS_MANAGEMENT_BODY_MERGE_FORM_ATTRIBUTES

Show more

ブーリアン

true

Whether the uploaded files should be removed after serving the request.

If true the uploaded files stored in quarkus.http.body-handler.uploads-directory will be removed after handling the request. Otherwise, the files will be left there forever.

Environment variable: QUARKUS_MANAGEMENT_BODY_DELETE_UPLOADED_FILES_ON_END

Show more

ブーリアン

true

Whether the body buffer should pre-allocated based on the Content-Length header value.

If true the body buffer is pre-allocated according to the size read from the Content-Length header. Otherwise, the body buffer is pre-allocated to 1KB, and is resized dynamically

Environment variable: QUARKUS_MANAGEMENT_BODY_PREALLOCATE_BODY_BUFFER

Show more

ブーリアン

false

A comma-separated list of ContentType to indicate whether a given multipart field should be handled as a file part. You can use this setting to force HTTP-based extensions to parse a message part as a file based on its content type. For now, this setting only works when using RESTEasy Reactive.

Environment variable: QUARKUS_MANAGEMENT_BODY_MULTIPART_FILE_CONTENT_TYPES

Show more

list of string

The accept backlog, this is how many connections can be waiting to be accepted before connections start being rejected

Environment variable: QUARKUS_MANAGEMENT_ACCEPT_BACKLOG

Show more

int

-1

Path to a unix domain socket

Environment variable: QUARKUS_MANAGEMENT_DOMAIN_SOCKET

Show more

string

/var/run/io.quarkus.management.socket

Enable listening to host:port

Environment variable: QUARKUS_MANAGEMENT_DOMAIN_SOCKET_ENABLED

Show more

ブーリアン

false

Set whether the server should use the HA PROXY protocol when serving requests from behind a proxy. (see the PROXY Protocol). When set to true, the remote address returned will be the one from the actual connecting client. If it is set to false (default), the remote address returned will be the one from the proxy.

Environment variable: QUARKUS_MANAGEMENT_PROXY_USE_PROXY_PROTOCOL

Show more

ブーリアン

false

If this is true then the address, scheme etc. will be set from headers forwarded by the proxy server, such as X-Forwarded-For. This should only be set if you are behind a proxy that sets these headers.

Environment variable: QUARKUS_MANAGEMENT_PROXY_PROXY_ADDRESS_FORWARDING

Show more

ブーリアン

false

If this is true and proxy address forwarding is enabled then the standard Forwarded header will be used. In case the not standard X-Forwarded-For header is enabled and detected on HTTP requests, the standard header has the precedence. Activating this together with quarkus.http.proxy.allow-x-forwarded has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

Environment variable: QUARKUS_MANAGEMENT_PROXY_ALLOW_FORWARDED

Show more

ブーリアン

false

If either this or allow-forwarded are true and proxy address forwarding is enabled then the not standard Forwarded header will be used. In case the standard Forwarded header is enabled and detected on HTTP requests, the standard header has the precedence. Activating this together with quarkus.http.proxy.allow-forwarded has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

Environment variable: QUARKUS_MANAGEMENT_PROXY_ALLOW_X_FORWARDED

Show more

ブーリアン

Enable override the received request’s host through a forwarded host header.

Environment variable: QUARKUS_MANAGEMENT_PROXY_ENABLE_FORWARDED_HOST

Show more

ブーリアン

false

Configure the forwarded host header to be used if override enabled.

Environment variable: QUARKUS_MANAGEMENT_PROXY_FORWARDED_HOST_HEADER

Show more

string

X-Forwarded-Host

Enable prefix the received request’s path with a forwarded prefix header.

Environment variable: QUARKUS_MANAGEMENT_PROXY_ENABLE_FORWARDED_PREFIX

Show more

ブーリアン

false

Configure the forwarded prefix header to be used if prefixing enabled.

Environment variable: QUARKUS_MANAGEMENT_PROXY_FORWARDED_PREFIX_HEADER

Show more

string

X-Forwarded-Prefix

Configure the list of trusted proxy addresses. Received Forwarded, X-Forwarded or X-Forwarded-* headers from any other proxy address will be ignored. The trusted proxy address should be specified as the IP address (IPv4 or IPv6), hostname or Classless Inter-Domain Routing (CIDR) notation. Please note that Quarkus needs to perform DNS lookup for all hostnames during the request. For that reason, using hostnames is not recommended.

Examples of a socket address in the form of host or host:port:

  • 127.0.0.1:8084

  • [0:0:0:0:0:0:0:1]

  • [0:0:0:0:0:0:0:1]:8084

  • [::]

  • localhost

  • localhost:8084

Examples of a CIDR notation:

  • ::/128

  • ::/0

  • 127.0.0.0/8

Please bear in mind that IPv4 CIDR won’t match request sent from the IPv6 address and the other way around.

Environment variable: QUARKUS_MANAGEMENT_PROXY_TRUSTED_PROXIES

Show more

list of TrustedProxyCheckPart

All proxy addresses are trusted

Determines whether the entire permission set is enabled, or not. By default, if the permission set is defined, it is enabled.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__ENABLED

Show more

ブーリアン

The HTTP policy that this permission set is linked to. There are 3 built in policies: permit, deny and authenticated. Role based policies can be defined, and extensions can add their own policies.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__POLICY

Show more

string

required

The methods that this permission set applies to. If this is not set then they apply to all methods. Note that if a request matches any path from any permission set, but does not match the constraint due to the method not being listed then the request will be denied. Method specific permissions take precedence over matches that do not have any methods set. This means that for example if Quarkus is configured to allow GET and POST requests to /admin to and no other permissions are configured PUT requests to /admin will be denied.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__METHODS

Show more

list of string

The paths that this permission check applies to. If the path ends in /* then this is treated as a path prefix, otherwise it is treated as an exact match. Matches are done on a length basis, so the most specific path match takes precedence. If multiple permission sets match the same path then explicit methods matches take precedence over matches without methods set, otherwise the most restrictive permissions are applied.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__PATHS

Show more

list of string

Path specific authentication mechanism which must be used to authenticate a user. It needs to match HttpCredentialTransport authentication scheme such as 'basic', 'bearer', 'form', etc.

Environment variable: QUARKUS_MANAGEMENT_AUTH_PERMISSION__PERMISSIONS__AUTH_MECHANISM

Show more

string

The roles that are allowed to access resources protected by this policy. By default, access is allowed to any authenticated user.

Environment variable: QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__ROLES_ALLOWED

Show more

list of string

**

Permissions granted to the SecurityIdentity if this policy is applied successfully (the policy allows request to proceed) and the authenticated request has required role. For example, you can map permission perm1 with actions action1 and action2 to role admin by setting quarkus.http.auth.policy.role-policy1.permissions.admin=perm1:action1,perm1:action2 configuration property. Granted permissions are used for authorization with the @PermissionsAllowed annotation.

Environment variable: QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__PERMISSIONS

Show more

Map<String,List<String>>

Permissions granted by this policy will be created with a java.security.Permission implementation specified by this configuration property. The permission class must declare exactly one constructor that accepts permission name (String) or permission name and actions (String, String[]). Permission class must be registered for reflection if you run your application in a native mode.

Environment variable: QUARKUS_MANAGEMENT_AUTH_POLICY__ROLE_POLICY__PERMISSION_CLASS

Show more

string

io.quarkus.security.StringPermission

The path this header should be applied

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__PATH

Show more

string

/*

The value for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE

Show more

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS

Show more

list of string

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES

Show more

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER

Show more

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS

Show more

list of string

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__ORDER

int

期間フォーマットについて

To write duration values, use the standard java.time.Duration format. See the Duration#parse() javadoc for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

About the MemorySize format

A size configuration option recognises string in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?. If no suffix is given, assume bytes.

7. リバースプロキシーの背後での実行

Quarkusは、ヘッダーを生成するプロキシ(例: X-Forwarded-Host )を通じてアクセスすることで、元のリクエストに関する情報を保持することができます。Quarkusは、これらのヘッダーの値を使用して、プロトコル、ホスト、ポート、URIなどの情報を自動的に更新するように設定できます。

この機能を有効にすると、サーバーが情報詐称などのセキュリティ上の問題にさらされる可能性があります。リバースプロキシーの後ろで実行する場合のみ有効にしてください。

マネジメントインタフェースにこの機能を設定するには、 src/main/resources/application.properties に次の設定を記述します:

quarkus.management.proxy.proxy-address-forwarding=true

quarkus.management.proxy.allow-forwardedsrc/main/resources/application.properties で設定することで、この動作を標準の Forwarded ヘッダーに限定する( X-Forwarded のバリアントを無視する)ことができます:

quarkus.management.proxy.allow-forwarded=true

あるいは、 src/main/resources/application.properties で以下の設定をすることにより( allow-forwarded の代わりに allow-x-forwarded であることに注意)、 X-Forwarded-* ヘッダーを優先することもできます:

quarkus.management.proxy.proxy-address-forwarding=true
quarkus.management.proxy.allow-x-forwarded=true
quarkus.management.proxy.enable-forwarded-host=true
quarkus.management.proxy.enable-forwarded-prefix=true

サポートされている転送アドレスヘッダーは以下の通りです。

  • Forwarded

  • X-Forwarded-Proto

  • X-Forwarded-Host

  • X-Forwarded-Port

  • X-Forwarded-Ssl

  • X-Forwarded-Prefix

ヘッダーの種類( ForwardedX-Forwarded-* )の両方が有効な場合、 Forwarded のヘッダーが優先されます。

ForwardedX-Forwarded の両方のヘッダーを使用すると、クライアントがプロキシによって上書きされないヘッダーでリクエストを偽造することができるため、セキュリティ上問題があります。

クライアントリクエストから予期しない Forwarded または X-Forwarded-* ヘッダーを取り除くようにプロキシが設定されているようにして下さい。

8. Kubernetes

QuarkusはKubernetesのメタデータを生成する際に、マネジメントインタフェースが有効かどうかをチェックし、それに応じてプローブを設定します。結果の記述子は、メインのHTTPポート(名前: http )とマネジメントポート(名前: management )を定義しています。Health プローブ(HTTPアクションを使用)とPrometheusスクレイプURLは、 management ポートを使用して設定されます。

KNative

KNative#8471 が解決されるまで、KNativeはコンテナが複数のポートを公開することをサポートしていないため、マネジメントインタフェースを使用することはできません。

9. セキュリティ

Basic 認証は、以下のプロパティを使用して有効にすることができます:

quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Require all access to /q/* to be authenticated
quarkus.management.auth.permission.all.policy=authenticated
quarkus.management.auth.permission.all.paths=/q/*

また、パスごとに異なる権限を使用したり、ロールバインディングを使用したりすることも可能です:

quarkus.management.enabled=true
# Enable basic authentication
quarkus.management.auth.basic=true
# Configure a management policy if needed, here the policy `management-policy` requires users to have the role `management`.
quarkus.management.auth.policy.management-policy.roles-allowed=management

# For each endpoint you can configure the permissions
# Health used the management-policy (so requires authentication + the `management` role)
quarkus.management.auth.permission.health.paths=/q/health/*
quarkus.management.auth.permission.health.policy=management-policy

# Metrics just requires authentication
quarkus.management.auth.permission.metrics.paths=/q/metrics/*
quarkus.management.auth.permission.metrics.policy=authenticated

QuarkusのBasic認証の詳細は、 Basic認証ガイド に記載されています。