Use VS Code Extension#

This section walks you through the steps required to install the ACE Configurator VS Code extension and shows you how to use it to download, browse, edit, and upload configurations.

Important

The extension is typically used in conjunction with the ACE Configurator microservice. This section gives an overview of the extension’s features, but does not explain how to setup the microservice. We highly recommend going through Setting up ACE Configurator for a step-by-step guide on how to setup the microservice and the extension together.

Install the VS Code Extension#

Prerequisites#

An instance of the ACE Configurator microservice must be running and to operate on the Kubernetes microservices you would like to edit from VS Code. See Setting up ACE Configurator for a step-by-step guide on how to setup the microservice with the extension.

The VS Code desktop application must be installed on your computer. The extension has been tested on version 1.98.

Note

The extension typically also works on self-hosted VS Code for web, such as coder/coder-server, although this workflow is not supported officially.

Install from VS Code Extension Marketplace#

The extension can be installed from the VS Code Extension Marketplace.

Start the Extension#

  1. Click the “file” icon on the left sidebar to open the file explorer.

  2. Click the “ACE CONFIGURATOR” panel at the bottom left (see screenshot below).

  3. You should be prompted to open a VS Code workspace. A workspace is just a directory on your computer. Configurations will be saved to the workspace, so we recommend creating an empty directory and using it as your workspace.

  4. Open the “ACE CONFIGURATOR” panel again.

  5. You should be prompted to set the ACE Configurator URL. This setting will be stored in the .vscode/settings.json file for future reference and debugging purposes.

A screenshot of the extension's initial state in the VS Code desktop application. The panel is titled "ACE CONFIGURATOR" and contains a button titled "Set Configurator API URL"

Manage Configurations#

The extension lists all microservices that have been set up to be configured with the ACE Configurator. Each microservice can have one or more configurations. A configuration can be downloaded, browsed, edited, uploaded, and in some cases, restored.

A screenshot of the extension's configurations screen. The panel contains a button "Download all", and two configurations that are not synced yet

The typical lifecycle of a configuration is as follows:

  1. A Kubernetes configuration is downloaded from the Kubernetes service to your local file system

  2. The user browses and edits configurations on their local file system

  3. To apply their local changes to the Kubernetes service, the user clicks “Upload” on the specific configuration

  4. The user repeats steps 2 and 3 to iterate and refine the service they are working on

Download, Browse and Edit Configurations#

When downloading a configuration, the files are stored in your local workspace. This allows you to browse and edit them from VS Code’s file explorer. Because files are stored on the client’s file system, you may also access and modify configurations from other editors.

A configuration is downloaded using its “Download” button. Alternatively, you may click the “Download all” button to download all configurations at once.

Tip

Since the extension detects configuration changes from your local system, you may manage them with source control software like git.

Note

VS Code and the ACE Configurator extension must be running to detect changes made by other softwares.

A screenshot of the extension's configurations screen. One configuration is synced, while the other indicates "modified locally"

When a file has been created or modified locally, either through VS Code or another editor, the file is flagged with an “M” icon, and the config appears as “Modified locally” in the extension’s UI. In this state, you can choose to upload the configuration to the microservice, as documented in the next section.

Upload Configurations#

After a configuration has been downloaded and edited locally, the extension allows you to upload the configuration to the microservice. Once the upload is complete, the configuration has been applied on the microservice.

A screenshot of the extension's configurations screen after the user clicked "upload". A notification indicates that the configuration has been successfully uploaded. Both configurations are now in "synced" state.

Warning

Do not modify files while the configuration is being updated. This can compromise the integrity of the configuration.

Restore Configurations#

Some configurations can be restored from their original state when the microservice was initially created. In practice, this is the case for configurations that are backed by a Kubernetes ConfigMap. Configurations backed by volumes cannot be restored.

On this page