Hello Actions

Let's start writing our Hello World action. This action will include a single button with the text "Quick Start".

({ context }) => {
   return (
      <Button>
         Quick Start
      </Button>
   );
};

As you can see, an action is essentially some JavaScript code, specifically a React component. If you are not familiar with JavaScript and React, I recommend learning the basics of React before continuing.

This component contains only one button and receives a context parameter. We will discuss more about the context later. For now, you only need to know that the context provides some data related to the area where the action will appear.

Terrakube uses Ant Design (antd) components, so by default, all antd components are available when you are developing an action.

Testing our Hello world action

To create the action in your Terrakube instance, navigate to the Organization settings and click the Create Action button

Add the following data and click the save button.

If you go to any workspace, the quick start button should appear.

Adding Interaction to the Action

Now let's add some interaction to the button. In the next example, we will use the Ant Design Messages component.

({ context }) => {
  const [messageApi, contextHolder] = message.useMessage();

  const showMessage = () => {
    messageApi.success('Hello Actions');
  };

  return (
    <>
      {contextHolder}
      <Button onClick={showMessage}>
        Quick Start
      </Button>
    </>
  );
};

Now, if you update the action code, navigate to any workspace, and click the Quick Start button, you will see the Hello Actions message.

Using the context to access workspace data

To make this action more useful, you can make use of the context. The context is an object that contains data based on the Action Type. If you want to see all the data available for every action type, check the Action Context documentation.

For our quick start action, we will add the name of the workspace to the message.

({ context }) => {
  const [messageApi, contextHolder] = window.antd.message.useMessage();

  const showMessage = () => {
    messageApi.success(`Hello ${context.workspace.attributes.name}`);
  };

  return (
    <>
      {contextHolder}
      <Button onClick={showMessage}>
        Quick Start
      </Button>
    </>
  );
};

Update the action code using the code above, click the Quick Start button, and you will see the message now displays the Workspace Name.

Using display criteria

f you view a couple of workspaces in the organization, you will see the "Quick Start" button always appears. This is useful if your action serves a general purpose, but there are scenarios where you want to display the action only for workspaces in a specific organization, with a specific version of Terraform, and so on.

In those cases, you will use display criteria, which provides a powerful way to decide when an action will appear or not. If you remember, we set the display criteria to true before. Now let's modify the criteria to show the action only if the workspace contains a specific name.

Navigate to the Actions settings and change the display criteria to:

context.workspace.attributes.name === "sample_simple"

(You can use another workspace name if you don't have the "sample_simple" workspace.)

Now the button will appear only for the sample_simple workspace. If you notice, the display criteria is a conditional JavaScript code. So you can use any JavaScript code to display the action based on a regular expression, for organizations starting with certain names, or even combine multiple conditions.

At this moment, our action only interacts with Terrakube data. However, a common requirement is to access other APIs to get some data, for example, to connect to the GitHub API to get the issues related to the workspace, or to connect to a cloud provider to interact with their APIs.

In these cases, we can make use of the Action Proxy. The proxy provides a way to connect to other backend services without needing to directly configure CORS for the API. The proxy also provides a secure way to use credentials without exposing sensitive data to the client.

Let's add a simple interaction using mock data from the JSONPlaceholder API that reads the comments from a post.

({ context }) => {
  const [dialogVisible, setDialogVisible] = useState(false);
  const [loading, setLoading] = useState(false);
  const [comments, setComments] = useState([]);

  const fetchData = async () => {
    setLoading(true);
    try {
      const response = await axiosInstance.get(`${context.apiUrl}/proxy/v1`, {
        params: {
          targetUrl: 'https://jsonplaceholder.typicode.com/posts/1/comments',
          proxyheaders: JSON.stringify({
            'Content-Type': 'application/json',
          }),
          workspaceId: context.workspace.id
        }
      });

      setComments(response.data);
      setDialogVisible(true);
    } catch (error) {
      console.error('Error fetching data:', error);
      message.error('Error fetching data');
    } finally {
      setLoading(false);
    }
  };

  const closeDialog = () => {
    setDialogVisible(false);
  };

  return (
    <>
      <Button
        type="default"
        onClick={fetchData}
        loading={loading}
      >
        Quick Start
      </Button>

      <Modal
        title="Comments"
        visible={dialogVisible}
        onCancel={closeDialog}
        footer={[
          <Button key="close" onClick={closeDialog}>
            Close
          </Button>,
        ]}
      >
        {comments.map((comment) => (
          <div key={comment.id} style={{ marginBottom: '10px' }}>
            <p><b>ID:</b> {comment.id}</p>
            <p><b>Name:</b> {comment.name}</p>
            <p><b>Email:</b> {comment.email}</p>
            <p><b>Comment:</b> {comment.body}</p>
          </div>
        ))}
      </Modal>
    </>
  );
};

Now if you click the Quick Start button, you will see a dialog with the comments data from the API. The proxy allows to interact with external apis and securely manage credentials. To know more about the Actions proxy check the documentation.

Now, if you click the Quick Start button, you will see a dialog with the comments data from the API. The proxy allows you to interact with external APIs and securely manage credentials. To learn more about the Actions proxy, check the documentation.

Summary

Actions in Terrakube allow you to enhance the Workspace experience by creating custom interactions and functionalities tailored to your needs. You can start by exploring the Built-in Actions to understand their implementation and gain more experience.

Actions are React components, and you define an Action Type to determine where the action will appear within the interface. Using Display Criteria, you can specify the precise conditions under which an action should be displayed, such as for specific organizations or Terraform versions.

Additionally, the Action Proxy enables integration with external APIs, securely managing credentials without requiring CORS configuration on the Terrakube front end. This is particularly useful when you don't have control over the external API's CORS settings.

The Action Proxy allows you to call other APIs without needing to add the Terrakube frontend to the CORS settings, which is particularly useful if you don't have access to configure CORS. Additionally, it can be used to inject Workspace variables and Global variables into your requests.

Calling the Action Proxy

The proxy supports POST, GET, PUT, and DELETE methods. You can access it using the axiosInstance variable, which contains an Axios object.

To invoke the proxy, use the following URL format: ${context.apiUrl}/proxy/v1

({ context }) => {
   const fetchData = async () => {
    try {
      const response = await axiosInstance.get(`${context.apiUrl}/proxy/v1`, {
        params: {
          targetUrl: 'https://jsonplaceholder.typicode.com/posts/1/comments',
          proxyheaders: JSON.stringify({
            'Content-Type': 'application/json',
          }),
          workspaceId: context.workspace.id
        }
      });

      console.log(response.data);
    } catch (error) {
      console.error('Error fetching data:', error);
    }
 
  };

When calling the Action Proxy, use the following required parameters:

• targetUrl: Contains the URL that you want to invoke.

• proxyHeaders: Contains the headers that you want to send to the target URL.

• workspaceId: The workspace ID that will be used for some validations from the proxy side

Injecting Variables via the Action Proxy

If you need to access sensitive keys or passwords from your API call, you can inject variables using the template notation ${{var.variable_name}}, where variable_name represents a Workspace variable or a Global variable.

Example Usage

const response = await axiosInstance.post(`${context.apiUrl}/proxy/v1`, {
  targetUrl: 'https://api.openai.com/v1/chat/completions',
  proxyHeaders: JSON.stringify({
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ${{var.OPENAI_API_KEY}}'
  }),
  workspaceId: context.workspace.id,
  proxyBody: JSON.stringify({
    model: 'gpt-4',
    messages: updatedMessages,
  })
}, {
  headers: {
    'Content-Type': 'application/json',
  }
});

In this example:

• ${{var.OPENAI_API_KEY}} is a placeholder for a sensitive key that will be injected by the proxy.

• proxyBody contains the data to be sent in the request body.

• proxyHeaders contains the headers to be sent to the target URL.

• targetUrl specifies the API endpoint to be invoked.

• workspaceId is used for validations on the proxy side.

By using the Action Proxy, you can easily interact with external APIs while using Terrakube's capabilities to manage and inject necessary variables securely.

Display Criteria offer a flexible way to determine when an action will appear. While you can add logic inside your component to show or hide the action, using display criteria provides additional advantages:

• Optimize Rendering: Save on the loading cost of each component.

• Multiple Criteria: Add multiple display criteria based on your requirements.

• Conditional Settings: Define settings to be used when the criteria are met.

A display criteria is a JavaScript condition where you can use the data from the Action Context to decide if the action will appear.

Examples

Always display the action

true

Display the action for Workspaces with specific Terraform version.

context.workspace.attributes.terraformVersion === "1.0.0"

Display the action for Azure resources

context.state.provider.includes("azurerm")

Display the action only for Azure VM

context.state.type.includes("azurerm_virtual_machine")

Display Criteria Settings

You can set specific settings for each display criteria, which is useful when the action provides configurable options. For example, suppose you have an action that queries GitHub issues using the GitHub API and you want to display the issues using GraphQL. Your issues are stored in two different repositories: one for production and one for non-production.

In this case, you can create settings based on the display criteria to select the repository name. This approach allows your action code to be reusable. You only need to change the settings based on the criteria, rather than modifying the action code itself.

For instance:

• Production Environment: For workspaces starting with prod, use the repository name for production issues.

context.workspace.attributes.startsWith("prod")

• Non-Production Environment: Use the repository name for non-production issues

context.workspace.attributes.startsWith("dev")

By setting these configurations, you ensure that your action dynamically adapts to different environments or conditions, enhancing reusability and maintainability.

Sensitive Settings

You might be tempted to store secrets inside settings; however, display criteria settings don't provide a secure way to store sensitive data. For cases where you need to use different credentials for an action based on your workspace, organization or any other condition, you should use template notation instead. This approach allows you to use Workspace Variables or Global Variables to store sensitive settings securely.

For example, instead of directly storing an API key in the settings, you can reference a variable:

• For the development environment: ${{var.dev_api_key}}

• For the production environment: ${{var.prod_api_key}}

For the previous example, you will need to create the variables at workspace level or use global variables with the names dev_api_keyand prod_api_key

For more details about using settings in your action and template variables check Action Proxy.

Multiple Display Actions

You can define multiple display criteria for your actions. In this case, the first criteria to be met will be applied, and the corresponding settings will be provided via the context.

The context object contains data related to the Workspace that you can use inside the action. The properties depends on the Action Type.

context.workspace

Contains the workspace information in the Terrakube api format. See the docs for more details on the properties available.

Examples

• context.workspace.id: Id of the workspace

• context.workspace.attributes.name: Name of the workspace

• context.workspace.attributes.terraformVersion: Terraform version

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.settings

Contains the settings that you configured in the display criteria.

Examples

• context.settings.Repository: the value of repository that you set for the setting. Example:

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.state

For workspace/action this property contains the full terraform or open tofu state. For workspace/resourcedrawer/action and workspace/resourcedrawer/tab contains only the section of the resource

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.apiUrl

Contains the Terrakube api Url. Useful if you want to use the Action Proxy or execute a call to the Terrakube API.

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

In this section:

Action Types define where an action will appear in Terrakube. Here is the list of supported types:

Workspace/Action

The action will appear on the Workspace page, next to the Lock button. Actions are not limited to buttons, but this section is particularly suitable for adding various kinds of buttons. Use this type for actions that involves interaction with the Workspace

Workspace/ResourceDrawer/Action

The action will appear for each resource when you click on a resource using the Overview Workspace page or the Visual State Diagram. Use this when an action applies to specific resources, such as restarting a VM or any actions that involve interaction with the resource.

Workspace/ResourceDrawer/Tab

The action will appear for each resource when you click on a resource using the Overview Workspace page or the Visual State Diagram. Use this when you want to display additional data for the resource, such as activity history, costs, metrics, and more.

For this type, theLabel property will be used as the name of the Tab pane.

Terrakube actions allow you to extend the UI in Workspaces, functioning similarly to plugins. These actions enable you to add new functions to your Workspace, transforming it into a hub where you can monitor and manage your infrastructure and gain valuable insights. With Terrakube actions, you can quickly observe your infrastructure and apply necessary actions.

Key Benefits of Terrakube Actions:

• Extend Functionality: Customize your Workspace with additional functions specifics to your needs.

• Monitor Infrastructure: Gain real-time insights into your infrastructure with various metrics and monitoring tools.

• Manage Resources: Directly manage and interact with your resources from within the Workspace.

• Flexibility: Quickly disable an action if it is not useful for your organization or set conditions for actions to appear, such as if a resource is hosted in GCP or if the workspace is Dev.

• Cloud-Agnostic Hub: Manage multi-cloud infrastructure from a single point, providing observability and actionability without needing to navigate individual cloud portals.

Examples of Terrakube Actions:

• Manage Infrastructure: Restart your Azure VM or add an action to quickly navigate to the resource in the Azure portal directly from Terrakube.

• Monitor Metrics: Track and display resource metrics for performance monitoring using tools like Prometheus, Azure Monitor or AWS Cloudwatch.

• Integrate with Tools: Seamlessly integrate with tools like Infracost to display resource and Workspace costs.

• AI Integration: Use AI to diagnose issues in your Workspaces. By integrating with models like OpenAI, Claude, and Gemini, you can quickly resolve errors in your infrastructure.

• Project and Incident Management: Integrate with Jira, GitHub Issues, and ServiceNow to identify Workspaces with pending work items or reported errors.

• Documentation: Link your Confluence documentation or wiki pages in your preferred tool, allowing quick access to documents related to your Workspace infrastructure.

Built-in Actions

Terrakube provides several built-in actions that you can start using some are enabled by default. Please refer to the documentation for detailed information on each action, including usage and setup instructions.

Developing Actions

If you are interested in creating your own actions, you only need knowledge of JavaScript and React, as an action is essentially a React component. For more details please check our quick start guide, or visit our GitHub Terrakube Actions repository to see some examples, contribute new actions or suggest improvements.

Creating an Action

After you develop your action. To create a new action in Terrakube:

1. Navigate to the settings in any Terrakube organization.

1. Click the Add Action button.

1. Provide the required information as detailed in the table below:

1. Click the Save button.

Description

The Open In Azure Portal action is designed to provide quick access to the Azure portal for a specific resource. By using the context of the current state, this action constructs the appropriate URL and presents it as a clickable button.

Display Criteria

By default, this Action is disabled and when enabled will appear for all the azurerm resources. If you want to display this action only for certain resources, please check .

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, click the Open in Azure button.

• You will be able to see the Azure portal for that resource.

The following actions are added by default in Terrakube. However, not all actions are enabled by default. Please refer to the documentation below if you are interested in activating these actions.

General

• : Adds a button to quickly navigate to the Terraform registry documentation for a specific resource.

• : Adds a new panel to visualize the state attributes and dependencies for a resource.

Azure

• Adds a button to quickly navigate to the resource in the Azure Portal.

• : Adds a button to restart the Azure VM directly from the workspace overview.

Monitor

• : Adds a panel to visualize the metrics for the resource.

AI

• : Adds a button to ask questions or get recommendations using OpenAI based on the workspace data.

Description

The Resource Details action is designed to show detailed information about a specific resource within the workspace. By using the context of the current state, this action provides a detailed view about the properties and dependencies in a tab within the resource drawer.

Display Criteria

By default this Action is enabled and will appear for all the resources. If you want to display this action only for certain resources, please check .

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, you will see a new tab Details with the resource attributes and dependencies.

Description

The Open Documentation action is designed to provide quick access to the Terraform registry documentation for a specific provider and resource type. By using the context of the current state, this action constructs the appropriate URL and presents it as a clickable button.

Display Criteria

By default this Action is enabled and will appear for all the resources. If you want to display this action only for certain resources, please check .

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, Click the Open documentation button

• You will be able to see the documentation for that resource in the Terraform registry

Description

The Restart VM action is designed to restart a specific virtual machine in Azure. By using the context of the current state, this action fetches an Azure access token and issues a restart command to the specified VM. The action ensures that the VM is restarted successfully and provides feedback on the process.

Display Criteria

By default, this Action is disabled and when enabled will appear for all resources that have resource type azurerm_virtual_machine. If you want to display this action only for certain resources, please check .

Setup

This action requires the following variables as or in the Workspace Organization:

• ARM_CLIENT_ID: The Azure Client ID used for authentication.

• ARM_CLIENT_SECRET: The Azure Client Secret used for authentication.

• ARM_TENANT_ID: The Azure Tenant ID associated with your subscription.

• ARM_SUBSCRIPTION_ID: The Azure Subscription ID where the VM is located.

Usage

• Navigate to the Workspace Overview or the Visual State and click on a resource name.

• In the Resource Drawer, click the "Restart" button.

• The VM will be restarted, and a success or error message will be displayed.

Description

The Azure Monitor Metrics action allows users to fetch and visualize metrics from Azure Monitor for a specified resource.

Display Criteria

By default, this Action is disabled and when enabled will appear for all the azurerm resources. If you want to display this action only for certain resources, please check .

Setup

This action requires the following variables as or in the Workspace Organization:

• ARM_CLIENT_ID: The Azure Client ID used for authentication.

• ARM_CLIENT_SECRET: The Azure Client Secret used for authentication.

• ARM_TENANT_ID: The Azure Tenant ID associated with your subscription.

• ARM_SUBSCRIPTION_ID: The Azure Subscription ID where the VM is located.

Usage

• Navigate to the Workspace Overview or the Visual State and click on a resource name.

• Click the Monitor tab to view metrics for the selected resource.

• You can view additional details for the metrics using the tooltip.

• You can see more details for each chart by navigating through it.

Description

The Ask Workspace action allows users to interact with OpenAI's GPT-4o model to ask questions and get assistance related to their Terraform Workspace. This action provides a chat interface where users can ask questions about their Workspace's Terraform state and receive helpful responses from the AI.

Display Criteria

By default, this Action is disabled and when enabled will appear for all resources. If you want to display this action only for certain resources, please check display criteria.

Setup

This action requires the following variables as Workspace Variables or Global Variables in the Workspace Organization:

• OPENAI_API_KEY: The API key to authenticate requests to the OpenAI API. Please check this guide in how to get an OPEN AI api key

Usage

• Navigate to the Workspace and click on the Ask Workspace button.

• Enter your questions and click the Send button or press the Enter key.