API Gateway Registration and Configuration

Do the following to register various components with your API gateway.

What is an API gateway?

An API gateway is a micro services gateway that serves as the central relay for all communications in the StorNext Unified UI (UUI) framework. All communications between UUI components and managed nodes flow through the gateway.
Do I need an API gateway?

An API gateway is a core component of the UUI framework and you must have at least one API gateway installed to support the required communications. An API gateway is also a required component for StorNext 7 Capacity Based Reporting to the myStorNext portal.
What is the purpose of registering my system with an API gateway?

You register your system with an API gateway so that it becomes a managed node in the framework.

Beginning with StorNext 7, you can use the snrest gateway command to register your system with an API Gateway.

Note: The command does not work if your API Gateway is enabled with full authentication. Use the snrest gateway import command.

snrest gateway register myapi-gateway.mydomain.com

If your API Gateway is configured to use a different port, then you can also specify the port. The example below illustrates how to specify port 9559. For example:

snrest gateway register https://myapi-gateway.mydomain.com:9559

See Display the Configuration for a Registration on Your API Gateway to display the configuration for your registration.

The output includes a <url> value. For example:

{
    "url": "https://myapi-gateway.mydomain.com:8443",
    "admin_url": "https://myapi-gateway.mydomain.com:8443",
    "access_token_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/client-access-token",
    "refresh_token_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/client-refresh-token",
    "public_key_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/public-key",
    "logout_url":  "https://myapi-gateway.mydomain.com:8443/api/authentication/client-logout",
    "auth_client_id": "mydomain-app-registration",
    "auth_client_secret": "M37219!XWe#qMe$MHcyGEd7S"
}

snrest gateway import <filename>

Note: Only use the command if you configured your API Gateway to use different values other than the default configuration.

Use the command to import the configuration information from your API Gateway. The <filename> argument specifies the name of the file that contains the API Gateway's contact and authentication information.

To export the output from the apigw endpoint regauth config to a file, run the following on your API Gateway:

/opt/quantum/api-gateway/bin/apigw endpoint regauth config <name> > <filename>

Note: The <name> argument specifies the name of the registration on your API Gateway. See Show All Registration Names on Your API Gateway.

Example

/opt/quantum/api-gateway/bin/apigw endpoint regauth config quantum-app-registration > apiconfiguration

Below is an example of the information in the file:

{
    "url": "https://myapi-gateway.mydomain.com:8443",
    "admin_url": "https://myapi-gateway.mydomain.com:8443",
    "access_token_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/client-access-token",
    "refresh_token_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/client-refresh-token",
    "public_key_url": "https://myapi-gateway.mydomain.com:8443/api/authentication/public-key",
    "logout_url":  "https://myapi-gateway.mydomain.com:8443/api/authentication/client-logout",
    "auth_client_id": "mydomain-app-registration",
    "auth_client_secret": "M37219!XWe#qMe$MHcyGEd7S"
}

After you create the file, if necessary, transfer the file to the system where you plan to run the snrest gateway import <filename> command.

snrest gateway remove

Use the command to remove the gateway configuration that you created by using the snrest gateway admin-url <url> command or the snrest gateway import <filename> command.

Note: The command does not remove the current registration with your API Gateway; to remove the current registration with your API Gateway, run the snrest gateway unregister command, or it does not register the next time StorNext services are started.

To remove the current registration with your API Gateway, use the snrest gateway unregister command. For example:

snrest gateway unregister

Note: The command removes the current registration, but the underlying system attempts to re-establish the connection with your API Gateway over time.

Do the following to completely remove the registration with your API Gateway so that you can register with a new API Gateway. The process cleans any existing states out from your old API Gateway before you can register with a new API Gateway, given that the old API Gateway is running when you unregister.

Run the command below (or run the snrest gateway import <filename> command):

snrest gateway admin-url <hostname>

Run the command below:

snrest gateway unregister

Run the command below:

snrest gateway register

Use the snrest gateway show command to display your current gateway configuration:

snrest gateway show

Below is an example of the output:

{
    "url": "https://myapi-gateway.mydomain.com:8443",
    "admin_url": "https://myapi-gateway.mydomain.com:8443"
}

Use the snrest gateway status command to display the current connections for the individual endpoints of StorNext to the gateway:

snrest gateway status

Below is an example of the output if your system is registered:

All endpoints registered with the gateway

Below is an example of the output if your system is not registered:

No endpoints registered with the gateway

Note: Use the snrest gateway status -d command to display internal registration information for several internal parts of StorNext that register REST endpoints and provides an internal view that is used by Quantum Technical Support and Service personnel.

Below is an example of the snrest gateway status -d output:

{
    "host": {
        "url": "https://myhost.mydomain.com:37692",
        "service_type": "host",
        "service_name": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "service_path": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "challenge": "REDACTED",
        "use_gateway": true,
        "display_name": "myhost",
        "full_name": "myhost.mydomain.com",
        "registered": true,
        "gateway": {
            "url": "https://myapi-gateway.mydomain.com:8443",
            "admin_url": "https://myapi-gateway.mydomain.com:8443"
        }
    },
    "nameserver": {
        "url": "https://myhost.mydomain.com:37692",
        "service_type": "nameserver",
        "service_name": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "service_path": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "challenge": "REDACTED",
        "use_gateway": true,
        "display_name": "myhost",
        "full_name": "myhost.mydomain.com",
        "registered": true,
        "gateway": {
            "url": "https://myapi-gateway.mydomain.com:8443",
            "admin_url": "https://myapi-gateway.mydomain.com:8443"
        }
    },
    "mdc": {
        "url": "https://myhost.mydomain.com:37692",
        "service_type": "mdc",
        "service_name": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "service_path": "a56dc42f-4c02-46ad-90ee-94f2be3a0eb8",
        "challenge": "REDACTED",
        "use_gateway": true,
        "display_name": "myhost",
        "full_name": "myhost.mydomain.com",
        "registered": true,
        "gateway": {
            "url": "https://myapi-gateway.mydomain.com:8443",
            "admin_url": "https://myapi-gateway.mydomain.com:8443"
        }
    },
    "fs/snfs1-5c102a1f-cd1a-40fe-a4ee-67e273a1909b": {
        "url": "https://myhost.mydomain.com:38933",
        "service_type": "fs",
        "service_name": "snfs1-5c102a1f-cd1a-40fe-a4ee-67e273a1909b",
        "service_path": "5c102a1f-cd1a-40fe-a4ee-67e273a1909b",
        "challenge": "REDACTED",
        "use_gateway": true,
        "display_name": "snfs1",
        "full_name": "snfs1",
        "registered": true,
        "gateway": {
            "url": "https://myapi-gateway.mydomain.com:8443",
            "admin_url": "https://myapi-gateway.mydomain.com:8443"
        }
    },
    "fs/snfs2-753e48b2-a4f7-454a-9218-1c3a6c2deb48": {
        "url": "https://myhost.mydomain.com:37946",
        "service_type": "fs",
        "service_name": "snfs2-753e48b2-a4f7-454a-9218-1c3a6c2deb48",
        "service_path": "753e48b2-a4f7-454a-9218-1c3a6c2deb48",
        "challenge": "REDACTED",
        "use_gateway": true,
        "display_name": "snfs2",
        "full_name": "snfs2",
        "registered": true,
        "gateway": {
            "url": "https://myapi-gateway.mydomain.com:8443",
            "admin_url": "https://myapi-gateway.mydomain.com:8443"
        }
    },
    "snsm": {
        "url": "https://myhost.mydomain.com:39356",
        "service_type": "snsm",
        "service_name": "fsrestd",
        "challenge": "REDACTED",
        "use_gateway": false
    }
}

The snrest gateway ping command tests connectivity to the API Gateway. If the API Gateway cannot be contacted, then an error message is displayed and the command exits with a non-zero exit status. By default, the command below pings the currently configured API Gateway:

snrest gateway ping

Alternatively, you can ping a specific URL with:

snrest gateway ping <url>

or use a file with the gateway configuration with the -f option:

snrest gateway ping -f <filename>

In this latter case, the file specified is the same form used with snrest gateway import <filename>.

See the snrest command in the StorNext Man Pages Reference Guide for complete details.

Do the following to register your Appliance Controller with an API Gateway.

Follow the procedures in Register Your MDC with Your API Gateway.
At the prompt, enter the following to validate the registration status of your Appliance Controller:

qtmcontroller -c 'nas product status'

Example output for Appliance Controller 3.1.1 (or earlier):

NAS status: disabled

NAS License: Valid Product Key

Registration status: Registered

Registration server: https://myapi-gateway.mydomain.com:9559

Example output for Appliance Controller 4.0 (or later):

NAS status: disabled

NAS License: Valid Product Key

Registration status:

https://10.62.187.249:9559 - Registered

https://myapi-gateway.mydomain.com:9559 - Registered

See the snrest command in the StorNext Man Pages Reference Guide for complete details.

Do the following to register FlexSync with an API Gateway.

Follow the procedures in Register Your MDC with Your API Gateway.
At the prompt, enter the following:

/bin/systemctl restart flexsyncadmind

If you need to create an initial FlexSync user, enter the following two commands:

/opt/quantum/flexsync/bin/flexsyncauth -a -U <username> -P <password> -d flexsyncd

/opt/quantum/flexsync/bin/flexsyncauth -a -U <username> -P <password> -d flexsyncadmind

If you configured an API gateway and need to reload changes from your API gateway configuration, product key, or license without restarting your flexsyncadmind daemon, use the config-reload command.

Note: Your API gateway configuration parameters define the URLs and credentials you can use to register and unregister the API gateway. To configure your API gateway parameters, use the command /usr/cvfs/bin/snrest. See the snrest command in the StorNext Man Pages Reference Guide for details.

Note: You can only perform this operation using the CLI.

At the prompt, enter the following command:

/opt/quantum/flexsync/bin/flexsyncadmin -U <username> -P <password> config-reload

Example

/opt/quantum/flexsync/bin/flexsyncadmin -U admin -P password config-reload

Command Parameters

`<username>`	User name for flexsyncadmind.
`<password>`	Password for flexsyncadmind.
`config-reload`	This option allows you to reload changes from your API gateway configuration, product key, or license without restarting your flexsyncadmind daemon.

If the command succeeds and the changes from your API gateway configuration are reloaded, then the following output appears:

Flexsyncadmind has reloaded config successfully.