Stage Configuration Files

Overview

With F5 NGINX Instance Manager, you can easily pre-configure and stage NGINX configuration files, so you can quickly publish them to individual NGINX instances or instance groups whenever you’re ready.

See Also:
For instructions on creating and working with instance groups, refer to the topic Working with instance groups.

Before You Begin

To complete the instructions in this guide, you need the following:

  • Instance Manager is installed, licensed, and running.

Stage an Instance’s Config

To stage an NGINX instance’s configuration for publication to other instances or instance groups, follow these steps:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Instances.
  3. On the Instances Overview page, select an instance in the list that has the configuration you want to stage.
  4. Select Edit Config.
  5. Make your desired changes to the instance’s config files. The config analyzer will let you know if there are any errors.
  6. To stage your changes so you can publish them later, select Save as and provide a name for the staged config.
  7. Select Save.
  8. To view the staged config, select Staged Configs on the left menu. The staged config should appear in the list.

Create a New Staged Config

Follow these steps to create a new staged configuration:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Staged Configs.

  3. Select Create.

  4. On the Create Config form, complete the necessary fields:

    • Config name: Give the staged config a name.
    • Config files root directory: specify the root directory where configuration files can be written to and read from. The default is /etc/nginx/.
    • Aux files root directory: specify the root directory where auxiliary files can be written to and read from. The default is /etc/nginx.
  5. Select Create.

  6. On the Overview page, select the staged config you just created.

  7. Select Add File.

  8. Specify the file path and file name. For example, /etc/nginx/conf.d/default.conf.

  9. Select Create.

  10. Type or paste the contents of the file in the configuration editor.

  11. Repeat steps 6–9 to add other files.

  12. Select Save when you’re done.


Update a Staged Configuration

To update a staged configuration:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Staged Configs.
  3. From the list of staged configs, select one you want to update.
  4. Edit the staged configuration files as needed. The config analyzer will let you know if there are any errors.
  5. Select Save to save the configuration.

Publish Staged Configurations

To publish a staged configuration to an NGINX instance or instance group:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Staged Configs.
  3. From the list of staged configs, select the one you want to publish.
  4. Select Publish to.
  5. Select the NGINX instance or instance group to publish the staged config to.
  6. Select Publish.

Add Hash Versioning to Staged Configs (API Only)

With the Instance Manager REST API, you can add a commit hash to NGINX configurations if you use version control, such as Git. This will allow you to retrieve a configuration with a unique version identifier.

See Also:

You can use tools such as curl or Postman to interact with the Instance Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/[nim|platform]/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.


To add a commit hash to a new or staged staged config using the REST API, send an HTTP POST or PUT request to the Configs endpoint.

Method Endpoint
POST or PUT /configs

The following table lists the parameters to include when adding version control identifiers to a config:

Field Type Possible Values
Description
Required Default value
externalID string

Commit hash, 1–150 characters

For example, 521747298a3790fde1710f3aa2d03b55020575aa.

The commit hash.

No null
externalIdType string git,
other

The type of commit that was used for the config update.

If the externalID isn’t specified, the externalIdType reverts automatically to other.

No other

JSON request
{
  "configName": "test-staged",
  "configFiles": {
  "rootDir": "/etc/nginx",
  "files": [
      {
      "contents": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==",
      "name": "/etc/nginx/nginx.conf"
      }
  ]
  },
  "auxFiles":
  {
      "rootDir": "/etc/nginx/aux",
      "files": []
  },
  "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
  "externalIdType": "git"
}

This JSON defines an NGINX configuration with the following settings:

  • Specifies the configuration name and root directory for auxiliary and configuration files.
  • Lists the configuration files with their contents and name; contents are base64 encoded,
  • Specifies an external ID and type as version control identifiers.
Important:
If you edit an NGINX configuration in the Instance Manager web interface or directly on the data plane, the previous hashed commit information will lost: the externalID will revert to null and externalIdType will revert to other automatically. The same result will occur if you don’t specify the externalId when making updates using the REST API.

To view a staged config, send an HTTP GET request to the Configs endpoint.

Method Endpoint
GET /configs/{config_uid}

To view a staged config with a version-controlled hash, send an HTTP GET request to the Configs endpoint and specify the externalID.

Method Endpoint
GET /configs/{config_uid}?externalId={commit_hash}
JSON response
{
  "configName": "test-staged",
  "createTime": "2023-02-28T20:12:15.677Z",
  "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
  "externalIdType": "git",
  "uid": "3693045a-5c4b-4fce-8929-ef362a29211b",
  "updateTime": "2023-02-28T20:12:15.677Z",
  "auxFiles": {
    "files": [],
    "rootDir": "/etc/nginx/aux"
  },
  "configFiles": {
    "files": [
      {
        "contents": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==",
        "name": "/etc/nginx/nginx.conf"
      }
    ],
    "rootDir": "/etc/nginx"
  }
}

What’s Next