Managing shared configurations

The analyze-deployment-tooling repository enables you to share a configuration or deploy a configuration that has been shared with you.

The shared configurations are recommended to be stored in a source control system such as Git. When you clone the shared configurations to your machine, they are cloned to a directory outside of the analyze-deployment-tooling project and then referenced.

To use a shared configuration in your environment, you provide the file path to the directory outside of the analyze-deployment-tooling project. Then, you choose which configs or assets to link to your environment.

When you use a source control system to manage the shared configurations, use VS Code to manage the repositories that they are contained in.

Prerequisites

Before you create or use a shared configuration, you must configure the analyze-deployment-tooling repository and create the dev environment:

Configuring your shared repositories location

  1. Open a terminal on your host machine.

    • On Windows, use a WSL terminal. Press Start -> wsl

  2. Navigate to the analyze-deployment-tooling/scripts directory.

  3. Run the configure-paths script with the shared task.
    For example:

    configure-paths -t shared

    By default the script creates a folder named my-configurations in your home directory For example /home/<user>/my-configurations. To specify a different path, use -p <path> with your path when you run the command.

  4. Reopen the analyze-deployment-tooling folder in a dev container.
    Press F1 (or Cmd+Shift+P in MacOS), type Dev Containers: Rebuild Container and select it.

After you have run the script, you can open the shared configurations folder in VS Code. In the same terminal as step 1, navigate to your shared configuration folder and open VS Code.

  1. For example, navigate to the directory:

    cd ~/my-configurations

  2. Open VS Code:

    code .

    This VS Code window is now referred to as the shared configurations VS Code window.

Sharing a configuration

You can share a configuration that you have already developed locally, or you can start developing a shared configuration from a new template.

  1. From the analyze-deployment-tooling VS Code window right-click the shared-repository template and copy it to the shared configurations VS Code window. Rename the folder to provide a name for your shared configuration.
    • On MacOS copy the template using the Finder app.
  2. You can share an existing config or asset, or create a new one to share.
    1. If you have local configs or assets that you want to start sharing, move the configs or assets from the analyze-deployment-tooling window into the new shared configurations window in the new shared-repository folder.
    2. If you are creating a new config, complete the instructions in Configuration development environment to create your config. When you copy the config-development template, copy it to the shared-repository your shared configurations VS Code window.
  3. To link your shared configuration into your analyze-deployment-tooling project, complete the steps in link configurations.

Note: We recommend to share your configurations through Git and the template configuration contains the files required to work with Git. To initialize the Git repository, run git init from the terminal the shared configuration folder. For example /home/<user>/my-configurations/shared-repository. For more information about how to use Git, see Git Reference Documentation.

Linking shared configurations

Link a shared configuration to your local environment.

  1. The configurations that can be linked must be contained within the path specified in rootDirectory. If your configuration is located in a git repository, you can clone it to the shared configurations path.
    For example, /home/<user>/my-configurations/shared-connectors.
    For information on how to clone a repository in VSCode, see Setting up a repository.

  2. Update the path-configuration.json file to reference the configuration to link:

    1. Add the paths for your repositories in the repositories array. The value for path is relative to the rootDirectory path.

      For example, to add the repository /home/<user>/my-configurations/shared-connectors the path-configuration.json file contains the following: 

      {
   "sharedConfigurations": {
       "rootDirectory": "/home/<user>/my-configurations",
       "repositories": [
           {
               "path": "shared-connectors"
           }
       ]
   }
}

  3. In the terminal, run:

    manage-environment -t link

Important: The repositories in the path-configuration.json are updated after you run the manage-environment -t link or the deploy commands.

Linking specific configs or assets

You can link to specific configs or assets from a shared configuration.

  • Use the configs key to specify an array of config names. Note: The backups associated with the config are also linked.
  • Use the connectors key to specify an array of connector names.
  • Use the additionalResources key to specify a list of additional resources.
  • Use the gatewaySchemas key to specify an array of gateway schema short names.
  • Use the extensions key to specify an array of extension names.
  • Use the plugins key to specify an array of i2 Notebook plugin names.
  • Use the dataSets key to specify an array of data set names.

For example to add the following:

  • law-enforcement config and backup from the shared-config repository
  • example-connector and example-connector2 connectors from the shared-connectors repository

The path-configuration.json file contains the following: 

{
  "sharedConfigurations": {
  "rootDirectory": "/home/<user>/my-configurations",
  "repositories": [{
    "path": "shared-configuration",
    "configs": [
      "law-enforcement"
    ]
  },
  {
    "path": "shared-connectors",
    "connectors": [
      "example-connector",
      "example-connector2"
    ]
  }]
  }
}