Create and manage add-on definitions in Terraform Developer Portal

Add-on definitions in Terraform Developer Portal package an HCP Terraform no-code module as optional supporting infrastructure, such as a database or cache, that application developers can install in their applications. Platform engineers typically create, edit, and delete add-on definitions to offer approved infrastructure patterns.

Add-on definition workflow

The following steps describe the procedure for creating add-on definitions:

1. For each add-on you want to create, define a no-code module in HCP Terraform that specifies a common infrastructure pattern.
2. Use the Terraform Developer Portal UI to create the add-on.

After the add-on is created, application developers can begin installing it to add additional capabilities to their applications.

Prerequisites

To create an add-on, you must meet the following requirements:

• An HCP Terraform organization on the Standard edition or higher to use HCP Terraform no-code modules and the private module registry. Refer to HCP Terraform pricing for plan details.

Create a no-code module

First, create a no-code module that defines the infrastructure pattern for the add-on. Refer to Design no-code ready modules for instructions.

You can reference the following variables in the module. Terraform Developer Portal sets the values when the application developer uses the add-on.

• developer_portal_add_on: The name of the add-on.
• developer_portal_add_on_definition: The name of the add-on definition used to create the add-on.
• developer_portal_application: The name of the application where the add-on is installed.

You can use these variables to label infrastructure resources in the no-code module so you can associate them with the Terraform Developer Portal application. Refer to Input variables for instructions on how to define variables in Terraform.

You may need to create organization-scoped or project-scoped variable sets within your HCP Terraform organization so your no-code modules can authenticate and interact with your cloud provider. Refer to Variable sets for more information.

Create an add-on definition

After you create the no-code module, complete the following steps in Terraform Developer Portal to create a new add-on definition:

1. Sign in to HCP Terraform and select the organization where you want to create your add-on.
2. In the navigation menu, click Developer Portal.
3. Click Add-ons in the sidebar, then click New Add-on.
4. Specify an identifier for the add-on in the Name field. This name must be unique from all other add-on definitions in your HCP Terraform organization.
5. Choose a no-code module to use as the source for the add-on from the Base module menu. No-code modules published in your organization's private registry appear in the menu.
6. Provide values for the input variables of the no-code module. Optionally, you can enable the User can configure this variable when creating an add-on checkbox to let users provide a value when they deploy the add-on.
7. Optionally, configure the execution mode that HCP Terraform uses to perform Terraform operations. By default, add-ons use the organization’s default execution mode. You can override the default by disabling Use Terraform organization's default mode and choosing one of the following options:
   • Remote: Run Terraform operations in HCP Terraform's infrastructure.
   • Agent: Use a self-managed agent pool. Refer to Manage Agent Pools to learn how to create and manage agent pools.
8. Click Continue.
9. Add a short description of the add-on in the Summary field. This field can be up to 110 characters. HCP Terraform presents the description when users deploy the add-on.
10. Specify instructions for application developers on how to use the add-on in the Developer Instructions field. This field supports markdown. Optionally, click Update from module's README to automatically populate this field with the value of the no-code module's README file. You can reference the following variables in the developer instructions. Refer to Terraform Developer Portal template and add-on variables for the complete list.
    • {{ .AddonName }}: Populates the name of the add-on in the instructions.
11. Click Save.

Edit an add-on definition

Modifying an add-on does not affect existing installations or supporting infrastructure created by the add-on. These changes only apply to new add-on installations.

Complete the following steps to edit an add-on definition:

1. Sign in to HCP Terraform and select the organization where you want to edit your add-on definition.
2. In the navigation menu, click Developer Portal.
3. Click Add-ons in the sidebar, then click on the add-on definition you want to modify.
4. Click the Manage menu, then select either Edit add-on or Edit inputs.
5. Update the desired fields.
6. Click Save.

Delete an add-on definition

Deleting an add-on does not delete the supporting infrastructure that was created with Terraform by the add-on. To remove the infrastructure, you must uninstall the add-on from an application or delete the Terraform resources and the HCP Terraform workspace associated with the Terraform Developer Portal add-on. Refer to Uninstall an add-on for instructions.

To delete an add-on definition, complete the following steps:

1. Sign in to HCP Terraform and select the organization where you want to delete your add-on definition.
2. In the navigation menu, click Developer Portal.
3. Click Add-ons in the sidebar, then click on the add-on definition you want to delete.
4. Click the Manage menu, then choose Delete.
5. In the Delete add-on dialog, enter "delete" and then click Delete add-on.

Next steps

To learn more about what you can do with Terraform Developer Portal after you created an add-on definition, refer to the following topics:

• Use an add-on to deploy supporting infrastructure
• Use a template to deploy and manage an application