Manage IaCM Workspace Plugin

Customize and configure the Manage IaCM Workspace plugin.

The Manage IACM Workspace plugin provides full lifecycle management for Harness IACM workspaces. Use it in your Harness pipelines to create, update, query, or delete IACM workspaces, manage variables and secrets, and perform bulk tag refactoring, all through a single, configurable plugin step.

Important notes

The plugin requires Python 3.11+ and Docker with buildx support at runtime.
The remove operation is destructive and irreversible. Use it only after confirming the correct workspace identifier.
Secret variables (PLUGIN_RESOURCE_VARS_SECRETS, PLUGIN_RESOURCE_VARS_ENVS_SECRETS) are passed as Harness secret references and are never logged or exposed in plain text.

Plugin image

harnesssolutionfactory/harness-manage-iacm-workspace:latest

Operation modes

Set the PLUGIN_SWITCH variable to control what the plugin does.

Mode

Alias

Description

main

register

Create or update an IACM workspace with variables and configuration

view

N/A

Query and retrieve workspace details; supports filtering by tags and attributes

remove

N/A

⚠️ Delete a workspace by identifier (destructive)

refactor

N/A

Bulk-update workspace tags and source classification

Use in Harness pipelines

Add the plugin as a Plugin step in your stage. The examples below cover each operation mode.

Go to Custom plugins to review how Harness Plugin Steps require the scripts to support environment variables with a prefix of PLUGIN_. However, when referring to these variables in the Harness pipeline plugin step, you must remove the prefix. For example, PLUGIN_HARNESS_URI becomes HARNESS_URI. This accounts for the appearance of a discrepancy between the actual environment variables and the settings on the plugin step.

Create or update a workspace

- step:
    type: Plugin
    name: Provision IACM Workspace
    identifier: provision_workspace
    description: Create or update IACM workspace with Terraform variables and configuration
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: main
        RESOURCE_NAME: my-workspace
        RESOURCE_OWNER: platform-team
        RESOURCE_VARS: '{"harness_platform_account":"<+account.identifier>","organization_name":"my-org"}'
        RESOURCE_VARS_SECRETS: '{"api_secret":"<+secrets.getValue(\"api_secret\")>"}'
        GIT_REPOSITORY_BRANCH: main
        GIT_REPOSITORY_CONNECTOR: org.harness_template_repo
        GIT_REPOSITORY_NAME: https://git.harness.io/account/org/repo.git
        GIT_REPOSITORY_PATH: workspaces/my-workspace
        HARNESS_PORTAL_RESOURCES: iacm/api/orgs/my-org/projects/my-project/workspaces
        HARNESS_PLATFORM_KEY: org.hsf_platform_api_key
        IAC_PROVISIONER_TYPE: opentofu
        IAC_PROVISIONER_VERSION: "1.10.0"
        WORKSPACE_ORG: my-organization
        WORKSPACE_PROJECT: my-project
        WORKSPACE_TAGS: '{"source":"official","type":"infrastructure"}'
        SHOULD_OVERWRITE_VARIABLES: "false"
        INCLUDE_HARNESS_ENVS: "false"
        DEBUG: "false"

Create a workspace from a template

- step:
    type: Plugin
    name: Create Workspace from Template
    identifier: create_templated_workspace
    description: Create IACM workspace from a Harness workspace template
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: main
        RESOURCE_NAME: template-workspace
        RESOURCE_OWNER: platform-team
        WORKSPACE_ORG: my-organization
        WORKSPACE_PROJECT: my-project
        WORKSPACE_TEMPLATE_IDENTIFIER: base-infrastructure
        WORKSPACE_TEMPLATE_VERSION: "1.0"
        RESOURCE_VARS: '{"environment":"production"}'

Query workspaces by tags

- step:
    type: Plugin
    name: Get Workspaces by Tags
    identifier: get_workspaces_by_tags
    description: Retrieve workspace identifiers filtered by tags
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: view
        WORKSPACE_TAGS: '{"source":"official","type":"infrastructure"}'
        RETURN_KEY: identifier
        IGNORE_HSF_SYSTEM: "true"

Filter workspaces by attribute

- step:
    type: Plugin
    name: Filter Workspaces by Attribute
    identifier: filter_workspaces
    description: Query a specific workspace by identifier
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: view
        FILTER_KEY: identifier
        FILTER_VALUE: my-workspace
        RETURN_KEY: identifier

Find workspaces tagged for decommission

- step:
    type: Plugin
    name: Get Workspaces for Decommission
    identifier: get_workspaces_decomm
    description: Find all workspaces marked for decommissioning
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: view
        WORKSPACE_TAGS: '{"decommission":"true"}'
        RETURN_KEY: identifier

Delete a workspace

This is a destructive, irreversible operation. Double-check PLUGIN_RESOURCE_NAME before running.

- step:
    type: Plugin
    name: Remove IACM Workspace
    identifier: remove_workspace
    description: Permanently delete an IACM workspace by identifier
    spec:
      connectorRef: <+input>
      image: harnesssolutionfactory/harness-manage-iacm-workspace:latest
      settings:
        HARNESS_ENDPOINT: <+pipeline.variables.harness_endpoint>
        HARNESS_ACCOUNT_ID: <+account.identifier>
        API_KEY: <+secrets.getValue("harness_api_key")>
        SWITCH: remove
        RESOURCE_NAME: workspace-to-delete

Settings reference

Connection and authentication

Setting

Type

Required

Default

Description

PLUGIN_HARNESS_ENDPOINT

String

Yes

N/A

Base URL of the Harness platform. Example: https://app.harness.io

PLUGIN_HARNESS_ACCOUNT_ID

String

Yes

N/A

Your Harness account identifier. Example: uZuUmmrnT4qQRx5XF0ZtkQ

PLUGIN_HARNESS_PORTAL_RESOURCES

String

Yes

N/A

API path to the workspace resources endpoint. Example: iacm/api/orgs/my-org/projects/my-project/workspaces

PLUGIN_HARNESS_PLATFORM_KEY

String

Yes

org.hsf_platform_api_key

Platform API key identifier used for authentication.

PLUGIN_API_KEY

String

Yes

N/A

API key for authenticating requests. Example: pat.xxxxx.xxxxx

Operation control

Setting

Type

Required

Default

Description

PLUGIN_SWITCH

String

main

Operation mode. One of: main, view, remove, refactor.

PLUGIN_DEBUG

Boolean

false

Set to true to enable verbose debug logging.

Workspace configuration

Setting

Type

Required

Default

Description

PLUGIN_RESOURCE_NAME

String

Yes

N/A

Workspace identifier. Example: my-workspace

PLUGIN_RESOURCE_OWNER

String

Yes

N/A

Team or individual that owns the workspace. Example: platform-team

PLUGIN_WORKSPACE_ORG

String

Harness_Platform_Management

Organization identifier within Harness.

PLUGIN_WORKSPACE_PROJECT

String

Solutions_Factory

Project identifier within the organization.

PLUGIN_WORKSPACE_TAGS

String (JSON)

{}

Key-value tags applied to the workspace. Used for filtering in view and refactor modes. Example: {"source":"official","type":"infrastructure"}

PLUGIN_WORKSPACE_TEMPLATE_IDENTIFIER

String

skipped

Workspace template ID. Required when provisioning from a template. Example: base-infrastructure

PLUGIN_WORKSPACE_TEMPLATE_VERSION

String

skipped

Version of the workspace template to use. Example: 1.0

Git repository settings

Setting

Type

Required

Default

Description

PLUGIN_GIT_REPOSITORY_BRANCH

String

Yes

main

Git branch to use for the workspace.

PLUGIN_GIT_REPOSITORY_CONNECTOR

String

Yes

org.Harness_Template_Library_Repo

Harness connector identifier for the Git repository.

PLUGIN_GIT_REPOSITORY_NAME

String

Yes

N/A

Full URL of the Git repository. Example: https://git.harness.io/account/org/repo.git

PLUGIN_GIT_REPOSITORY_PATH

String

N/A

Subdirectory path within the repository. Example: workspaces/my-workspace

IaC configuration

Setting

Type

Required

Default

Description

PLUGIN_IAC_PROVISIONER_TYPE

String

opentofu

IaC provisioner to use. Accepted values: opentofu, terraform.

PLUGIN_IAC_PROVISIONER_VERSION

String

1.8.0

Version of the provisioner. Example: 1.10.0

PLUGIN_IAC_PROVIDER_CONNECTOR

String

""

Harness connector for the IaC provider. Example: org.hsf_solutions_factory_connector

Variable management

Setting

Type

Required

Default

Description

PLUGIN_RESOURCE_VARS

String (JSON)

{}

Terraform input variables passed to the workspace. Example: {"key":"value","env":"prod"}

PLUGIN_RESOURCE_VARS_SECRETS

String (JSON)

{}

Terraform variables sourced from Harness secrets. Example: {"api_key":"secret_value"}

PLUGIN_RESOURCE_VARS_FILES

String (JSON Array)

[]

List of variable files to include. Example: ["terraform.tfvars","prod.tfvars"]

PLUGIN_RESOURCE_VARS_ENVS

String (JSON)

{}

Environment variables passed to the provisioner. Example: {"LOG_LEVEL":"info"}

PLUGIN_RESOURCE_VARS_ENVS_SECRETS

String (JSON)

{}

Environment variables sourced from Harness secrets. Example: {"API_SECRET":"secret"}

PLUGIN_OVERRIDES

String (JSON)

{}

Environment-specific variable overrides. Example: {"prod":{"key":"terraform_key"}}

PLUGIN_SHOULD_OVERWRITE_VARIABLES

Boolean

false

When true, replaces all existing variables. When false, merges with existing values.

Advanced settings

Setting

Type

Required

Default

Description

PLUGIN_INCLUDE_HARNESS_ENVS

Boolean

false

When true, injects standard Harness environment variables into the workspace.

PLUGIN_IS_EPHEMERAL

Boolean

false

When true, marks the workspace as ephemeral (short-lived, for temporary environments).

Filtering and query options (`view` mode)

Setting

Type

Required

Default

Description

PLUGIN_FILTER_KEY

String

N/A

Workspace attribute to filter by. Example: identifier, repository_connector

PLUGIN_FILTER_VALUE

String

N/A

Value to match against the filter key. Example: my-workspace

PLUGIN_RETURN_KEY

String

N/A

Workspace attribute to return in query results. Example: identifier

PLUGIN_IGNORE_HSF_SYSTEM

Boolean

false

When true, excludes internal HSF system workspaces from results.

Local development

Docker examples

The plugin can be run directly with Docker for local testing.

Create or update a workspace:

docker run --rm \
  -e PLUGIN_HARNESS_ENDPOINT=https://app.harness.io \
  -e PLUGIN_HARNESS_ACCOUNT_ID=your_account_id \
  -e PLUGIN_API_KEY=your_api_key \
  -e PLUGIN_SWITCH=main \
  -e PLUGIN_RESOURCE_NAME=my-workspace \
  -e PLUGIN_RESOURCE_OWNER=platform-team \
  -e PLUGIN_RESOURCE_VARS='{"harness_platform_account":"your_account","organization_name":"my-org"}' \
  -e PLUGIN_GIT_REPOSITORY_BRANCH=main \
  -e PLUGIN_GIT_REPOSITORY_CONNECTOR=org.harness_template_repo \
  -e PLUGIN_GIT_REPOSITORY_NAME=https://git.harness.io/account/org/repo.git \
  -e PLUGIN_GIT_REPOSITORY_PATH=workspaces/my-workspace \
  -e PLUGIN_HARNESS_PORTAL_RESOURCES=iacm/api/orgs/my-org/projects/my-project/workspaces \
  -e PLUGIN_HARNESS_PLATFORM_KEY=org.hsf_platform_api_key \
  -e PLUGIN_IAC_PROVISIONER_TYPE=opentofu \
  -e PLUGIN_IAC_PROVISIONER_VERSION=1.10.0 \
  -e PLUGIN_WORKSPACE_ORG=Harness_Platform_Management \
  -e PLUGIN_WORKSPACE_PROJECT=Solutions_Factory \
  -e PLUGIN_WORKSPACE_TAGS='{"source":"official","type":"infrastructure"}' \
  -e PLUGIN_SHOULD_OVERWRITE_VARIABLES=false \
  harnesssolutionfactory/harness-manage-iacm-workspace:latest

Query workspaces by tags:

docker run --rm \
  -e PLUGIN_HARNESS_ENDPOINT=https://app.harness.io \
  -e PLUGIN_HARNESS_ACCOUNT_ID=your_account_id \
  -e PLUGIN_API_KEY=your_api_key \
  -e PLUGIN_SWITCH=view \
  -e PLUGIN_WORKSPACE_TAGS='{"source":"official","type":"infrastructure"}' \
  -e PLUGIN_RETURN_KEY=identifier \
  -e PLUGIN_IGNORE_HSF_SYSTEM=true \
  harnesssolutionfactory/harness-manage-iacm-workspace:latest

Delete a workspace:

docker run --rm \
  -e PLUGIN_HARNESS_ENDPOINT=https://app.harness.io \
  -e PLUGIN_HARNESS_ACCOUNT_ID=your_account_id \
  -e PLUGIN_API_KEY=your_api_key \
  -e PLUGIN_SWITCH=remove \
  -e PLUGIN_RESOURCE_NAME=workspace-to-delete \
  harnesssolutionfactory/harness-manage-iacm-workspace:latest

PreviousHSF Plugins

NextPlugins Overview

Last updated 4 days ago

Was this helpful?

Important notes

Plugin image

Operation modes

Use in Harness pipelines

Create or update a workspace

Create a workspace from a template

Query workspaces by tags

Filter workspaces by attribute

Find workspaces tagged for decommission

Delete a workspace

Settings reference

Connection and authentication

Operation control

Workspace configuration

Git repository settings

IaC configuration

Variable management

Advanced settings

Filtering and query options (view mode)

Local development

Docker examples

Filtering and query options (`view` mode)