Configuration management

Deployment Manager offers configuration management features that let you customize your Instabase deployment. The Instabase UI exposes configuration options in the Deployment Manager Configs tab. To learn about customizing configuration with APIs, see the Deployment Manager API documentation.

How configuration management works with Deployment Manager

Configuration management is built on the concept of a base configuration modified by patches. The sum of your base configuration and applied patches is your materialized configuration. Your cluster always reflects the materialized configurations of all resources.

Base configurations are provided by Instabase, typically as a .zip file. When installing Instabase initially, you upload the base configurations file using the Instabase Installer UI or APIs. When a new version of Instabase is available, Instabase provides the updated base configurations file for that release. You can then upgrade your Instabase version by uploading the new base configurations .zip file.

All customers receive the same base configuration files for a given release version, but you can modify or add to your configuration using patches. Patches can be in YAML or JSON format and are used to selectively modify Kubernetes objects in the cluster.

Warning

Never directly edit the base configuration files provided by Instabase to make configuration changes. Always use the configuration management tools on the Configs and Base Configs tabs instead.

When patches are applied, Deployment Manager overlays the changes on top of the base configuration, generates a new materialized configuration, and pushes the new configuration to your Kubernetes cluster. During upgrades, any existing patches are automatically applied to the new base configuration, implementing your configuration changes on the new release version.

Info

Deployment Manager’s patch-based configuration management uses the Kubernetes paradigm of declarative management of Kubernetes objects using Kustomize. To learn more, see the Kubernetes documentation on Kustomize.

Resource label bindings

In configuration management, resource labels are used to group services that share a common property. For example, the label database is bound to all objects that have database connections and every service listed in Deployment Manager has the resource label all by default.

Resource labels make it possible to apply a single patch to multiple resources. When you bind multiple objects to a shared resource label, you can target that resource label (and every object bound to it) when applying a patch.

For example, if you have two services that each require a change to the BUILD_TIMESTAMP environment variable, you can apply the resource label change_timestamp to both resources. You can then create a patch that targets the change_timestamp label, and Deployment Manager applies the patch change to both labeled resources.

Info

To learn more about using resource label bindings with Deployment Manager, see the resource label APIs documentation.

The Deployment Manager Configs tab

The Deployment Manager Configs tab is the user interface where you can manage your deployment configurations. The Configs tab supports the following actions:

Info

Most of these actions can be performed via API call. To learn more, see the Deployment Manager APIs documentation.

Viewing current configurations

To view an object’s current config:

  1. Open the Deployment Manager Configs tab (All apps > Deployment Manager > Configs).

  2. Select an object from the Select an object dropdown.

    Note

    You can search for objects by name using the search bar in the Select an object dropdown.

    The object’s current config displays in the code display pane. The audit logs pane lists any patch changes or deletions to the object.

  3. Click Clear selection to remove the object filter.

Viewing configurations by resource label

You can also view all configurations grouped under a given resource label:

  1. Open the Deployment Manager Configs tab.

  2. Select a resource label from the Select a label dropdown.

    A dropdown listing all objects bound to the selected label appears. By default, one object’s config displays in the code display pane. The audit logs pane lists any patch changes or deletions to objects bound to the resource label.

  3. To navigate through all objects bound to the resource label, use the dropdown list to select an object or click Next and Prev to move through the list.

  4. Click Clear selection to remove the label filter.

Viewing patch audit logs

Changes to both base configurations and patches are tracked in the database to provide long-term durability and change histories. The right-hand pane of the Configs tab displays audit logs of patches applied or deleted across all objects. Audit logs include the following information:

  • The name of who applied the patch.

  • A 13-digit identifier, which you can click to copy a URL to the patch.

  • The name of the object.

  • The type of patch: YAML or JSON.

  • The date and time the patch was applied or deleted.

  • A description of the change.

Viewing an object’s patches

To view the patches applied to an object and view a specific patch:

  1. Open the Deployment Manager Configs tab.

  2. Select an object from the Select an object dropdown. All patches applied to the object display in the audit logs pane.

To view a specific patch’s details:

  1. Locate the patch in the audit logs pane.

  2. Click the arrow icon in the patch summary. The patch summary expands and displays the patch details.

Exporting current configurations

To export a .zip file of all your current configurations:

  1. Open the Deployment Manager Configs tab.

  2. Click Export all configs. Your configs export and download as a file named support_bundles.zip.

Applying patches

The Configs tab supports applying a patch to a specific object or to all objects bound to a given resource label, as well as applying a group of patches. To see examples of patches, see the patch library documentation. To learn how to modify and write your own patches, see the Writing YAML and JSON patches article.

Applying a patch to a single object

To apply a patch to a single object:

  1. Open the Deployment Manager Configs tab.

  2. Select an object from the Select an object dropdown.

  3. Click Enter patch. A code editor displays in the left pane and the current config displays on the right.

  4. Select a patch type from the patch type dropdown: YAML or JSON.

  5. Enter the patch manually or upload a patch file:

    • Manual: Enter the patch in the code editor pane.

    • Upload: Click Upload file and select your patch file from the file explorer. Supported file types are .yml or .json.

  6. Click Preview changes to run a diff between the current config and patch changes.

  7. Click Confirm changes.

  8. Enter a description of the patch change.

  9. Click Confirm.

Applying a patch to all objects bound to a resource label

To apply a patch to all objects bound to a resource label:

Info

See the Create resource label bindings API documentation to learn how to apply resource label bindings to objects.

  1. Open the Deployment Manager Configs tab.

  2. Select a resource label from the Select a label dropdown.

  3. Click Enter patch.

    A code editor displays in the left pane and the current config for one object displays on the right.

    Note

    While only one object’s config displays when applying the patch, the patch applies to all objects bound to the resource label. You do not need to apply the patch again to the next object bound to the resource label after completing these steps.

  4. Select a patch type from the patch type dropdown: YAML or JSON.

  5. Enter the patch manually or upload a patch file:

    • Manual: Enter the patch in the code editor pane.

    • Upload: Click Upload file and select your patch file from the file explorer. Supported file types are .yml or .json.

  6. Click Preview changes to run a diff between the current config and patch changes.

  7. Click Confirm changes.

  8. Enter a description of the patch change.

  9. Click Confirm.

Applying a group of patches

The Configs tab supports uploading a group of patches at one time. The need to upload a group of patches most commonly arises when the Instabase team provides a group of pre-validated patches with specified targets. Supported file types when uploading a group of patches are .zip, .tar.gz., and .tgz.

Tip

You can specify the order in which to apply individual patches within the group by adding a comment specifying the 0-index order to the top of the patch file. For example, to apply a particular patch first, add the comment # order: 0.

  1. Open the Deployment Manager Configs tab.

  2. Upload the group of patches:

    • Click Browse and select the file from your file explorer.

    • Drag and drop the file onto the pane labeled Select an object or label or drag compressed file.

  3. Click Apply patches.

  4. Enter a description of the patch change.

  5. Click Confirm.

Sharing patches

To share a link to a specific patch:

Note

The recipient must have access to the environment to view the patch in Deployment Manager. To share the patch’s JSON or YAML definition alone, you can copy the patch from the expanded patch summary.

  1. Open the Deployment Manager Configs tab.

  2. Select an object from the Select an object dropdown.

  3. Locate the patch in the audit logs pane.

  4. Click the 13-digit identifier listed in the patch summary. A URL to the patch copies to your clipboard.

Replaying patch changes

The patch replay feature lets you view how a given patch modified an object’s config at the time the patch was applied. Note that patch replay does not display a diff between the selected patch and the object’s current config.

To use patch replay:

  1. Open the Deployment Manager Configs tab.

  2. Select an object from the Select an object dropdown.

  3. Locate the patch in the audit logs pane.

  4. Click the arrow icon to expand the patch summary.

  5. Click See changes.

The code display pane displays a diff of all changes applied to the config by the patch, at the time the patch was applied.

Deleting patches

Deleting a patch removes the selected patch and no subsequently added patches, letting you rollback specific changes.

Note

When you delete a patch that was applied to all objects bound to a resource label, the patch is removed from all objects still bound to that resource label. Deleting the patch from one object through the Configs tab still removes the patch from all objects originally targeted by the patch.

To delete a patch:

  1. Open the Deployment Manager Configs tab.

  2. Select an object from the Select an object dropdown.

  3. Locate the patch in the audit logs pane.

  4. Click the arrow icon to expand the patch summary.

  5. Click Delete.

  6. Click Confirm.

Managing ConfigMap templates

Some ConfigMaps (kind: ConfigMap) are complex and don’t support partial patching, making them challenging to edit through user-defined patches. These ConfigMaps instead have a ConfigMap template with a defined set of editable parameters. The edited ConfigMap template is rendered as the generated ConfigMap, which is applied to your deployment.

ConfigMap templates are listed in the Base Configs tab, and have the following characteristics:

  • The object name typically begins with config.

  • The kind key has a value of ConfigMap.

  • The metadata contains a label of configType: template (metadata/labels/configType: template).

The generated ConfigMap is what’s displayed in the objects list on the Deployment Manager Configs tab. Generated ConfigMap objects share the above characteristics.

Editing ConfigMap templates

To edit a ConfigMap template’s generated ConfigMap:

  1. Open the Deployment Manager Configs tab (All apps > Deployment Manager > Configs).

  2. Select a generated ConfigMap object from the Select an object dropdown.

  3. Click Edit Config.

    Note

    Only template ConfigMaps display an Edit Config button. If the ConfigMap does not have an Edit Config button, using patches to edit the object is supported.

  4. From the Settings dialog, edit the ConfigMap’s parameters as needed.

    Info

    You can edit the ConfigMap from the Observability or All Config Parameters tab. The Observability tab lists commonly edited parameters, accompanied by descriptions, and offers a more user-friendly editing interface. The All Config Parameters tab lists all parameters as a JSON object and has a text-based editing interface. To learn more about observability parameters, see the configure observability alerting and federation documentation.

  5. Click Save.

Note

You can’t add new parameters to a ConfigMap template yourself. Editing the All Config Parameters JSON object to include new parameters doesn’t add those parameters to the generated ConfigMap. If you want to add or edit a parameter not listed in the All Config Parameters JSON object, contact Instabase Support for support with changing the ConfigMap template.

Keeping ConfigMap templates up-to-date

During installations or upgrades to Instabase version 23.07 or later, always apply the default_patches.zip file included in your installation package. Applying the default_patches.zip file ensures that ConfigMap templates’ default values, including any new parameters, are kept up-to-date.

Applying the default_patches.zip file does not override any changes previously made to a ConfigMap template’s generated ConfigMap. However, if you have previously made changes to a non-template version of a ConfigMap (such as config-prometheus-server or config-alertmanager) that now exists as a ConfigMap template (such as config-prometheus-recording-rules, config-alertmanager-routes, config-prometheus-targets or config-prometheus-alerting-rules), those changes are not automatically migrated upon your first installation or upgrade to an Instabase version that supports ConfigMap templates. After installing or upgrading to an Instabase version that supports ConfigMap templates, you must manually update the corresponding ConfigMap template with any previously defined custom values. The non-template version of a ConfigMap that now has a template version is no longer used or supported.

Tip

You can use the generated ConfigMap object’s patch history to review any changes previously made to the ConfigMap. Use this history as a guide when reapplying changes after an installation or upgrade.