Motivation

Web services available in the Router requires a number of plugins configured in order to be used. This burden could be moved from the user to the Router bootstrap phase so that such configuration could be autogenerated.

Related WorkLogs

• WL#8965 - REST interface
• WL#11890 - REST endpoint for health of routes
• WL#12441 - REST endpoints for metadata-cache
• WL#12816 - REST endpoints for routes
• WL#12817 - REST endpoints for router application
• WL#12952 - Authenticating HTTP Component against MySQL Innodb Cluster metadata

User Stories

As a admin user I want the "bootstrap step" to configure the router with the REST API to easily monitor the router.

Design Requirements

DR1

REST API communication MUST be authenticated

DR2

REST API communication MUST be conducted over secure channels

DR3

X509 certificates MUST be placed in the data directory

DR4

If the data directory contain any of the X509 certificate files then existing X509 certificate files should be used

DR5

X509 certificates MUST be created atomically, if there is an error during X509 certificate generation then all X509 generated files MUST be cleaned up

Goals

Allow enabling web interface service on the Router in the boostrap phase by generating suitable Router configuration.

FR1

REST API configuration MUST be added at bootstrap if --disable-rest is not specified.

FR2

New bootstrap configuration option '--https-port' taking a positive argument in range 1-65535 inclusive MUST be added.

FR3

If the REST API is not disabled then the HTTP server component MUST be enabled on port provided by '--https-port' option, or port 8443 if the option is not specified.

FR4

If the REST API is not disabled then X509 certificates MUST be created for Router and CA if they do not exist, subject to rules defined in HLS.

FR5

CA and Router certificates MUST be created at the data_folder configured by the user.

FR6

If the REST API is not disabled then the rest_api Router plugin MUST be enabled.

FR7

If the REST API is not disabled then the http Router plugin MUST be enabled. It MUST be configured to use TLS using the X509 generated certificates.

FR8

If the REST API is not disabled then the http authentication via the metadata-cache backend MUST be enabled.

Failure scenarios

FailReq1

Router MUST fail when '--https-port' is specified together with the '--disable-rest' option.

FailReq2

Router MUST fail when '--https-port' argument value is not in [1-65535] range.

FailReq3

Router MUST fail when X509 certificates could not be created during bootstrap.

Non-functional requirements

NFR1

When deciding whether to generate certificate and key files, Bootstrap will not check the existing key/certificate files for validity. If they exist, they will be assumed to be valid.

NFR2

User is responsible for ensuring that the port specified by the '--https-port' switch is not currently in use, nor will be used by the Router itself (e.g. Router's listening ports for incoming traffic).

NFR3

Auto-generated certificates do not provide means to verify host identity (certificate will contain an identity that is not required to match the hostname where the certificate is generated)

Bootstrap configuration options

Bootstrap procedure MUST by default enable REST web services. In order to achieve that an additional configuration MUST be generated and X509 certificates MUST be created.

Two new configuration options '--disable-rest' and '--https-port' should be added for the bootstrap phase, where '--https-port' depends on the '--disable-rest' and should not be be used simultaneously (bootstrap procedure should fail otherwise).

'--disable-rest'

Do not enable REST web services at bootstrap. No argument value is allowed for this option.

'--https-port'

Define what port should be used for HTTP server on the Router side. If the port specified could not be used for whatever reason then boostrap procedure should not fail. One integer number argument is expected with value in range 1-65535 inclusive. Default port 8443 should be used if no '--https-port' is specified.

X509 certificates

In order to set up a secure communication channel for the web service communication X509 certificates should be created and used.

If REST interface is enabled during bootsrap then the following files should be created if they do not exist:

"ca-key.pem"

file containing a RSA key used to sign the CA certificate

"ca.pem"

file containing a CA certificate

"router-key.pem"

file containing a RSA key used to sign the Router certificate

"router-cert.pem"

file containing a Router certificate signed with the CA certificate

Those files should be created inside a Router data directory. If any of the specified files already exist in the data directory then the following scenarios are possible:

• There are no existing certificate and key files in the data directory, in that case new certificates MUST be created.

• Data directory contains both Router certificate file and a RSA key file associated with it, in that case no new certificate files should be created and the existing ones should be used.

• Data directory contains some certificate or key files but Router certificate or RSA key file associated with it is missing, in that case bootstrap procedure MUST fail.

The following table summarises the behaviour (1 = exists, 0 = does not exist, * = either case)

In case of an error during the key/certificate generation the bootstrap MUST fail and all key/certificate files MUST be cleaned up.

Generated configuration

The following sections should be added in the Router configuration file if no '--disable-rest' is specified:

[http_server]
port=$HTTP_PORT
ssl=1
ssl_cert=$ROUTER_DATA_DIR/router-cert.pem
ssl_key=$ROUTER_DATA_DIR/router-key.pem

This configuration enables a HTTPS server communication over port $HTTP_PORT, which can be provided using a '--https-port' option or 8443 by default. SSL certificate and private key are stored in the $ROUTER_DATA_DIR which can be specified using a '--directory' option.

[rest_api]

Enable rest_api Router plugin.

[http_auth_backend:default_auth_backend]
backend = metadata_cache

Create an authentication backend named 'default_auth_backend' which is going to be used for authentication purposes. By default it should use the 'metadata_cache' authentication backend mechanism introduced in WL#12952. This will allow to manage user accounts using MySQL Shell.

[http_auth_realm:default_auth_realm]
backend = default_auth_backend
method = basic
name = default_realm

Create an authentication realm named 'default_auth_realm' using a 'default_auth_backend' backend.

[rest_router]
require_realm = default_auth_realm

Configure rest_router plugin to be used with 'default_auth_realm' authentication realm. This allows to monitor Router application status.

[rest_routing]
require_realm = default_auth_realm

Configure rest_routing plugin to be used with 'default_auth_realm' authentication realm. This allows to monitor Router routes status.

[rest_metadata_cache]
require_realm = default_auth_realm

Configure rest_metadata_cache plugin to be used with 'default_auth_realm' authentication realm. This allows to monitor Router metadata cache status.