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 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.

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

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.

In this section:

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.