# Welcome

Brainboard is an end-to-end solution to visually build & manage cloud infrastructures, collaboratively.

### What is it about?

{% embed url="<https://www.youtube.com/watch?v=A37Z1YgXYUI>" %}

Brainboard is a solution that helps you:

* Build your cloud infrastructure design with <mark style="color:$primary;">**Terraform/OpenTofu**</mark> resources.

{% hint style="success" %}
Automatically generates the Terraform code.
{% endhint %}

* Centralize your **cloud infrastructure** to establish a single source of truth.
* Standardize your **IaC process.**
* Lower the **learning curve** for <mark style="color:$primary;">**Terraform**</mark> and the cloud.
* Easily **onboard** new engineers and safely **offboard** those leaving.
* Create a **self-serve model** within your organization, where your teams easily consume your reference architectures.

<mark style="color:$primary;">**Brainboard**</mark> is a collaborative and innovative solution that natively integrates **IaC** best practices, enforces security and has an embedded **CI/CD** engine out of the box.

<figure><img src="/files/YncygNRmYcEmUEFiqrAv" alt=""><figcaption></figcaption></figure>

### Why?

<mark style="color:$primary;">**Brainboard**</mark> has been built by experienced engineers with more than 20 years of experience, for engineers, by using automation and AI to make building and managing cloud infrastructure easier, without reinventing the wheel.

Here are the reasons why <mark style="color:$primary;">**Brainboard**</mark> is a good fit for you:

* It helps you centralize all the management of the cloud infrastructure, literally from end to end, into one single & unique platform.
* Move fast securely: It is designed to be intuitive and easy to learn, while providing the full power of an embedded **CI/CD** to shift left fast.
* No one is left behind: Anyone can understand a design, and for those who want to go deeper, the Terraform code is next to the design.
* Lower the learning curve of the cloud and Terraform/IaC.
* Help organizations capture the maturity of their cloud journey in a system that scales as the processes and use cases grow.
* Document faithfully the state of your cloud infrastructure that is already provisioned. This documentation is in constant sync with reality.
* Structure the review and approval process of the cloud infrastructure.
* Encourage adoption of best practices as they are implemented natively.
* Having a system that easily integrates with the enterprise workload.
* Be able to predict cloud infrastructure deployment in terms of costs and configuration.

<figure><img src="/files/NaktKyyn2G1IIrYeqGkP" alt=""><figcaption></figcaption></figure>

### Brainboard & Terraform

Among the variety of tools in the **infrastructure as code (laC)** ecosystem, <mark style="color:$primary;">**Terraform**</mark> is the most used language in the space, where you only describe how you want your infrastructure to be. Then <mark style="color:$primary;">**Terraform**</mark> will provision/update your infrastructure to match the desired state.

Engineers use **vanilla&#x20;**<mark style="color:$primary;">**Terraform**</mark> to build their infrastructures. This is a manual process to write every line of code, test it, lint it, document it, and once approved, deploy it.

When they need to replicate the same stack, they either copy/paste and manually change variables or use scripts to help them do that.

<mark style="color:$primary;">**Brainboard**</mark>, on the other hand, removes the hassle of doing everything manually, saves time and reduces errors by leveraging automation and AI.

It uses <mark style="color:$primary;">**Terraform**</mark> as an execution layer and offers engineers a solution to build and manage production-grade cloud infrastructures without manually writing every line of code and glueing different tools together to deploy them.

<figure><img src="/files/iFs0RaY3DaUUaD4GePUG" alt=""><figcaption></figcaption></figure>

### How does Brainboard work?

Brainboard is composed of different services that work together, in harmony, as one application.

There are two main categories of services:

1. **Synchronous services**: These process the information of users and return the value in real time.

{% hint style="info" icon="code" %}
**Example:** Generating the Terraform code as the user designs the infrastructure.
{% endhint %}

2. **Asynchronous actions**: Users request actions to be done, and once completed, Brainboard informs them.

{% hint style="info" icon="code" %}
**Example:** Triggering an import from a cloud provider. Brainboard connects to the target cloud provider, lists the resources, then builds the design, the Terraform code and the Terraform state file. Once the import is done, the user is informed via email.
{% endhint %}

### Get in touch

We want to hear your feedback, listen to your feature requests, and answer your questions. Here is how you can reach out to us:

🗨️ **In app:** Click on the <mark style="color:$primary;">**`Help`**</mark> button in the top-right and select <mark style="color:$primary;">**`Ask us anything`**</mark>.

📧 **By email:** <mark style="color:$primary;">**<contact@brainboard.co>**</mark>

▶️ Follow our YouTube channel [here](https://www.youtube.com/channel/UCB0DLhFEgta83U62mQzxGPg)

💻 Product roadmap [here](https://roadmap.brainboard.co/roadmap)

### What's next?

Sign up [here](http://app.brainboard.co/register) to explore the platform, or reach out to our cloud architects team, who will be happy to help you get started and build your first use cases.


# Fast track

### 1. Create an account

Register [here](https://app.brainboard.co/register) to create your account. You can sign up with your Google or Microsoft login.

### 2. Create a new architecture

* Click on the <mark style="color:$primary;">**`New architecture`**</mark> button in the top left part.
* Select <mark style="color:$primary;">**`From scratch`**</mark> option.

<figure><img src="/files/6IObBdjkye03RnrMKPbQ" alt=""><figcaption></figcaption></figure>

### 3. Add cloud resources

Drag and drop cloud resources from the ***left bar*** to the design area to build your architecture. Customize the cloud configuration of the resources

#### Azure

<figure><img src="/files/BHd4qWMbV8EmFY3o3SEn" alt=""><figcaption></figcaption></figure>

#### AWS

<figure><img src="/files/kQCLSNKbJehgCVz9pxZm" alt=""><figcaption></figcaption></figure>

### 4. Inspect the auto-generated Terraform code

See the auto-generated **Terraform** code in the right pane.

Code for Azure & AWS resources:

<div><figure><img src="/files/d1dC09DylvHe0EU9i27X" alt=""><figcaption></figcaption></figure> <figure><img src="/files/c2LjM75u3gLh8X2cHkNN" alt=""><figcaption></figcaption></figure></div>

Please refer to the support providers page to have the complete list of all supported cloud providers.

### 5. Add your cloud credentials

If you want to deploy your architecture, add your preferred cloud provider credentials [here](https://app.brainboard.co/settings/integrations/cloud-providers).

<figure><img src="/files/WO5qQ9DcFYilAT66jx2r" alt=""><figcaption><p>Cloud credentials</p></figcaption></figure>

Example for **Azure** credentials.

<figure><img src="/files/HneUaVyuGg9a6Yk1Anub" alt=""><figcaption></figcaption></figure>

### 6. Trigger a plan

After adding your cloud credentials, you can trigger the **Terraform / OpenTofu** plan directly from the design area and get the output in real time.

<figure><img src="/files/AP337iPVQ8Dxza1FmbfS" alt=""><figcaption></figcaption></figure>

#### Execution output

The output of the plan execution becomes available in the <mark style="color:$primary;">**`Deployment`**</mark> tab in the right panel.

<figure><img src="/files/0HzKBAbtDkKXvC0YxzTz" alt=""><figcaption></figcaption></figure>


# Start with a template

### Overview

Using a template is one of the quickest ways to get started with Brainboard. By providing you with pre-built architecture templates, we ensure that you begin with a tried-and-true infrastructure design and save your time during the initial setup. You can always edit these templates as you need.

### **Starting with a template**

Here are the steps you can follow to begin with templates:

1. Once you are logged into your Brainboard account, navigate to the home page by clicking <mark style="color:$primary;">Home</mark> in the left menu.
2. Then, click <mark style="color:$primary;">`Create architecture`</mark> button in the <mark style="color:$primary;">**Recent architectures**</mark> section. As an alternative, you can click the <mark style="color:$primary;">`Create architecture`</mark> button available at the bottom of the left menu.

{% hint style="info" %}
As an alternative to the first two steps mentioned above, you can simply click on the <mark style="color:$primary;">**`Templates`**</mark> option in the left menu to begin with templates.
{% endhint %}

<figure><img src="/files/5Vi5wrJL24wk970YcHXS" alt=""><figcaption></figcaption></figure>

Once the menu opens, you have the following three primary paths to start your project.

* **From scratch**: Start with a blank canvas.
* **From your infrastructure**: Import existing Terraform files or sync from a cloud provider.
* **From a template**: Access the catalogue of pre-built designs.

3. Choose <mark style="color:$primary;">**`From a template`**</mark> to gain access to the template catalogue.

<figure><img src="/files/T3wS7VkYxn791ALXGOFx" alt=""><figcaption></figcaption></figure>

4. Next, to use the desired template, select it on the <mark style="color:$primary;">**Start from a template**</mark> screen by simply clicking on it.
5. Once you have selected your desired template, click the <mark style="color:$primary;">**`Use template`**</mark> option on the next screen. Here, you will be prompted with the <mark style="color:$primary;">**Create architecture from template**</mark> popup modal to confirm the template details.
   1. On top of this pop-up modal, you can view the total number of resources that are used in the selected template.
   2. **Project:** You can select the project to associate the new architecture design with.
   3. **Environment:** You can select the desired environment here. For example, **Development, UAT**, etc.
   4. **Architecture name:** Edit the name of the new architecture as you need.
   5. **Architecture description:** Provide any additional details of the architecture design.

Once you have finalised the new architecture details, you can click the <mark style="color:$primary;">**`Create architecture`**</mark> button given at the bottom right corner of the modal.

<figure><img src="/files/vl72ngkJZARPxCMDFQWg" alt=""><figcaption></figcaption></figure>

You will be navigated to the Brainboard canvas, where you can review your design and make further changes.

***

### Using a Template

After choosing a template, the visual diagram and associated `Terraform` code is loaded onto the design canvas, where you can:

1. Customize resources by manually renaming parts and changing variables to meet your unique needs.
2. Make use of <mark style="color:$primary;">**Brainy**</mark>: To change the template, use natural language prompts
3. Run Validation: To make sure the template's configuration is accurate inside your particular environment variables, run `Terraform` Validate.

{% hint style="info" %}
If your team frequently uses the same architecture patterns, storing them as **Private Templates** guarantees architectural uniformity and significantly speeds up subsequent deployment cycles.
{% endhint %}

***

Shared below is additional information to help you sort the template that best fits your needs.

### Filtering Templates

The templates catalogue screen provides powerful filtering tools to help you find the right architecture.

<mark style="color:$primary;">**Filters:**</mark> If you click on this option, the <mark style="color:$primary;">**Filters**</mark> pane will be expanded on the right side of the screen. where you can filter designs by:

* **Scope**
* **Terraform Providers**
* **Tags**

{% hint style="success" %} <mark style="color:$primary;">**Scope**</mark>: Select the source library for your templates. You can choose :

1. **All Scopes:** Displays every template available to you across both public and organizational libraries.
2. **Public:** Access a collection of high-quality architecture patterns provided by Brainboard that cover common cloud deployment scenarios.
3. **Organization:** Access your company’s internal library of private infrastructure patterns tailored specifically for your team.
   {% endhint %}

{% hint style="success" %} <mark style="color:$primary;">**Terraform Providers**</mark>**:** To view templates unique to that environment, choose your desired cloud provider(*<mark style="color:$primary;">AWS, Azure, GCP</mark>*`,` etc.).
{% endhint %}

{% hint style="success" %} <mark style="color:$primary;">**Tags**</mark>**:** Using tags, you can filter the specific infrastructure components like `Networking`, `Database`, `Compute`, or`Serverless`, etc.
{% endhint %}

{% hint style="info" %}
You can convert any architecture you have designed into a Private Template. This allows you to build a reusable collection of authorized infrastructure patterns, ensuring architectural uniformity and significantly accelerating future deployment cycles.
{% endhint %}

<mark style="color:$primary;">**Search bar**</mark>**:** To locate particular use cases, such as `landing zone`, `kubernetes`, `security`, you can utilize the search bar.<br>

<figure><img src="/files/l0VPYF10k63UhgQqudKS" alt=""><figcaption></figcaption></figure>

5. To make your view more user-friendly when selecting the desired filter, you can sort the filtered results by clicking the <mark style="color:$primary;">**`Name`**</mark>**&#x20;dropdown**. Options include sorting by

* Name (ascending/descending)
* Cloud provider(ascending/descending)
* date the template was last updated(ascending/descending)

<figure><img src="/files/WrtkjENIhczeCLxzDQxp" alt=""><figcaption></figcaption></figure>


# Use cases videos

### Build Azure Function App

{% embed url="<https://www.youtube.com/watch?v=8kLX8dEgFLM&t>" %}

### Build AWS EKS cluster

{% embed url="<https://www.youtube.com/watch?v=izZWR6B3KMQ>" %}


# Brainboard philosophy

{% hint style="info" %}
Brainboard has been built by engineers for engineers, and we started it as we were scratching our own itches.
{% endhint %}

### Background story

What was eye-opening to us at the beginning was to realize that most engineers go through the exact same steps to create a cloud infrastructure:

1. They start with a high-level design (HLD) on a whiteboard, paper, or even in the head of the engineer.

‼️ Even if you are building the infrastructure without a design, you have it in your mind. For example: This database will be in this security group, connected to this application, with this data flow, behind this load balancer, etc.

⚠️ If the team doesn't have a design, no one can review the architecture, and this usually leads to communication barriers.

2. When the design is done, they will translate it into code. Whether the code is written by the same team or a different one doesn't make any difference; the workflow stays the same.
3. This Terraform code will first be checked if it's valid (terraform plan or validate), then scanned for security, policies, naming conventions, costs, etc.

{% hint style="info" %}
This is what is called [shift left](/help-and-faq/glossary#shift-left) in the industry, where the feedback loop has to be short. You detect errors as early as possible, fix them and iterate until you are ready to deploy. Actually, not yet, as most of the time, you need to change the design a bit to make it match the Terraform implementation.
{% endhint %}

3. Once the design and code are validated, the deployment process starts either automatically or manually, with or without approval.\
   \
   ⇒ If it's automatic, it will be done through the CI/CD.
4. Then, come all the heavy things like managing secrets, collaboration with different people in the same team, cross teams, deploying multiple environments and the most painful of all is the drift.

‼️ It needs discipline to respect the process for every single change you have to do, and since it relies on humans, some of them just fall into the old habit, going straight to the console of the cloud provider and changing things manually.

💡At this point, let's assume that all the steps are aligned, and you provision the infrastructure successfully, then every change you want to introduce has to go through the same steps again and again. It's not a negative statement, by the way, it's just how the process should work.

<figure><img src="/files/RzSMcOURCgB566QowFY5" alt=""><figcaption></figcaption></figure>

### What did the engineers want?

We, as engineers, wanted this to change! We wanted it so badly that we said to ourselves, let's write a wish list: what we want in an ideal world? We started writing down:

* First, we wanted to rely on **automation** and didn't want to repeat ourselves, in a way that when we design, the code is automatically generated. Let's focus on Terraform, it's the most used one. OK!
* But we wanted to still have **control over the code** and be able to do what we are used to doing in Terraform: variables, outputs, loops, data blocks, modules, etc, and be able to manage multiple environments easily. No more manual tasks, please.
* And wanted to have the **shortest feedback loop** possible, so why not an embedded CI/CD with all the tools we use: tfsec, checkov, terrascan, OPA, infracost.
  * Oh, security should be a native part. No more running after engineers to comply and rely on discipline.
* We also wanted to push the boundaries, because **it's not about the tool itself but the workflow,** and wondered why not having a reference architecture catalogue available to anyone within the team, and we finally stopped reinventing the wheel. Sounds amazing, right?
* Finally, we dreamed about making it **enterprise-ready** with RBACs, private runners, live collaboration, SSO, private registries, and the list didn't stop.

<figure><img src="/files/BJT9ZZOHdioV2XHsssNj" alt=""><figcaption></figcaption></figure>

> ***Fast-forward, a few years later,\*\*\*\*\*\*\*\*&#x20;**<mark style="color:$primary;">**Brainboard**</mark>**&#x20;\*\*\*\*\*\*\*\*becomes the one platform of choice for end-to-end cloud infrastructure management that offers exactly the wish list we dreamed about.***
>
> ***Delivered and supported by the most talented engineers in the cloud, IaC and software engineering.***


# Design first


# One end-to-end platform

Unique end-to-end cloud infrastructure management solution


# Brainy

Design, modify, troubleshoot and validate your cloud architecture using natural language.

{% hint style="info" %}
This feature is in an **alpha stage** and open only to select users and customers through a waiting list.
{% endhint %}

## Overview

<mark style="color:$primary;">**Brainy**</mark> is an AI-powered assistant built directly into your Brainboard architecture workspace. It allows you to design, modify, troubleshoot, and validate cloud infrastructure using natural language.

Instead of manually configuring resources, you can simply describe what you want, and <mark style="color:$primary;">**Brainy**</mark> will update your architecture diagram and generate the corresponding Terraform configuration in real time.

Powered by advanced AI models (Anthropic Claude Sonnet 4.6 and Opus 4.6), <mark style="color:$primary;">**Brainy**</mark> acts as an intelligent co-pilot for infrastructure design, helping you move faster while maintaining full control and visibility.

<figure><img src="/files/tw3KyjcCAXpcQuvOFZAZ" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
It can take a while for <mark style="color:$primary;">**Brainy**</mark> to analyze the existing architecture, think, and generate results for the requested design configuration. However, you can view continuous progress in both the chat area and the design canvas.
{% endhint %}

<figure><img src="/files/X9ht3sXt7ZaADIYR7KqB" alt=""><figcaption></figcaption></figure>

***

## Key Capabilities

### 1. Real-Time Architecture Editing

<mark style="color:$primary;">**Brainy**</mark> can directly modify your diagram based on your instructions:

* Add new resources (AWS, Azure, GCP, etc.).
* Update existing components.
* Remove unnecessary resources.
* Create and manage supporting files (e.g., scripts, IAM policies).

### 2. Terraform Configuration Management

<mark style="color:$primary;">**Brainy**</mark> automatically handles Terraform configurations, including:

* Resource attributes and blocks.
* Variables, locals, and outputs.
* Structured and clean Terraform code generation.

<figure><img src="/files/WQZpRBRo6GcFHUpiWYoO" alt=""><figcaption></figcaption></figure>

### 3. Module Integration

You can use modules directly from your organization’s module catalog.

* Reuse predefined infrastructure components.
* Maintain consistency across projects.
* Speed up complex deployments.

{% hint style="warning" %}
Currently, <mark style="color:$primary;">**Brainy**</mark> can access only the modules that are already imported into Brainboard.
{% endhint %}

<figure><img src="/files/DKR0KIBxufg6zK2U4spk" alt=""><figcaption></figcaption></figure>

#### 4. Built-in validation

<mark style="color:$primary;">**Brainy**</mark> helps ensure your infrastructure is correct and deployable:

* Run `terraform plan`
* Run `terraform validate`
* Detect issues and fix them, for example:
  * Circular dependencies
  * Resources misconfiguration
  * Hierarchy problems

<figure><img src="/files/DTkTpjJl6Pefj00N8yis" alt=""><figcaption></figcaption></figure>

### 5. Pipeline Visibility

<mark style="color:$primary;">**Brainy**</mark> allows you to:

* View pipeline execution history.
* Access job logs.
* Understand what changes are being proposed.

<figure><img src="/files/HAT7qhxx9ledcyfCDqZs" alt=""><figcaption></figcaption></figure>

#### 6. Documentation Generation

When requested, <mark style="color:$primary;">**Brainy**</mark> can:

* Generate architecture README files.
* Update documentation as your system evolves.

<figure><img src="/files/wFkUgKixjUpkshkkleRx" alt=""><figcaption></figcaption></figure>

#### 7. Context Reference using <mark style="color:$primary;">@</mark>

In your prompt/command, you can mention a specific node or a resource that's used in your architecture design by using the <mark style="color:$primary;">**@**</mark> sign, and you will be presented with the list of the currently opened architecture resources/nodes. Once you start typing the resource/node name, the list will be filtered accordingly for you to choose your desired node.

<figure><img src="/files/rYq8hQqUpz7aUpzripLs" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The node names will appear in the list as the original resource names, and not at the node title.
{% endhint %}

<figure><img src="/files/KVHWom5a1pHUyoxWPKa1" alt=""><figcaption></figcaption></figure>

***

#### 8. Insights into Brainy's processing

By expanding the **Thought** option, you can also view <mark style="color:$primary;">**Brainy's**</mark> process or logic, based on which it gave you the results or responded to you.

<figure><img src="/files/KUu5mQbXB4uqMYATcfoj" alt=""><figcaption></figcaption></figure>

#### 9. Exporting Chat as a Markdown file

You can export the transcript of your chat with <mark style="color:$primary;">**Brainy**</mark> as a markdown (MD) file. To do so, simply click on the **vertical ellipsis** (the three dots) in the top right corner of the chat, and select the **`Export transcript`** option from the dropdown menu.

<figure><img src="/files/5cQTdXj7lb7Ql8JZOx6I" alt=""><figcaption></figcaption></figure>

***

#### 10. Redo/Undo changes

Whenever you make changes to your architecture design using <mark style="color:$primary;">**Brainy**</mark>, a clickable **Undo** option becomes available just below the last <mark style="color:$primary;">**Brainy's**</mark> message from Brainy confirming the change. Clicking on it will revert all the changes that were made up to that point in your current session of chat.

{% hint style="info" %}

* <mark style="color:$primary;">**Brainy**</mark> holds the history of changes that were made within the last 24 hours.
* Any changes made before the last 24 hours are discarded, except the last 10 changes that are older than 24 hours. In short, only the last 10 changes older than 24 hours are reversible.
  {% endhint %}

<figure><img src="/files/gknw2aL9lywPBG1KoNPN" alt=""><figcaption></figcaption></figure>

You can also redo/undo changes using a prompt in the chat. However, the 24-hour rule for undo remains the same.

<figure><img src="/files/CF1Zv9kxwFwHntGhFnew" alt=""><figcaption></figcaption></figure>

***

## Accessing Chat History

To access the <mark style="color:$primary;">**Brainy**</mark> chat history for any architecture design, simply launch the Brainy chat window, and there you will see the list of past chat sessions. You can also view the time it was created. For example, 30 minutes ago, 10 days ago, etc.

Click on any session that you want to view or continue with.

<figure><img src="/files/pksTUmYyBZRG5URvKUFM" alt=""><figcaption></figcaption></figure>

## Limitations

To ensure safety and control, <mark style="color:$primary;">**Brainy**</mark> has the following limitations:

* It cannot run `terraform apply` or `destroy.`
* It cannot access the internet.
* It cannot modify `providers.tf` (system-managed).
* It is limited to one architecture per conversation.
* It has no access to Terraform state files.
* It does not support user/org/permission management.
* It is focused only on cloud/infrastructure topics.
* It does not have a BYOK / self-hosted option yet (Brainboard team is collecting feedback).
* It supports only image files as attachments. Exported chat transcripts (md files), and PDF files are not supported as uploads/attachments as of now.

***

## Data & Privacy

<mark style="color:$primary;">**Brainy**</mark> is built with privacy and security in mind.

#### What is Shared with the AI

* Architecture content (resources, TF configs, variables, outputs).
* Conversation messages.
* Architecture metadata (name, description, provider versions).

#### What is NOT Shared

* Terraform state files.
* Credentials or secrets.
* Other architectures.
* Personal data.

#### Zero Data Retention (ZDR)

<mark style="color:$primary;">**Brainy**</mark> uses [Anthropic’s Zero Data Retention](https://platform.claude.com/docs/en/build-with-claude/api-and-data-retention) policy:

* No data is stored.
* No data is used for training.

***

## Alpha Access

<mark style="color:$primary;">**Brainy**</mark> is currently available in **alpha,** and the steps for alpha access are:

1. Join the waiting list.
2. The feature is enabled via a flag.
3. Receive documentation and walkthrough.
4. Provide feedback to maintain access.

{% hint style="warning" %}
Access is revoked if there is no usage for two weeks or no feedback is provided after follow-up.
{% endhint %}

{% hint style="info" %}
The feature is free during the alpha preview.
{% endhint %}

***

## Reporting Issues

When reporting an issue or providing feedback, it is recommended to copy the <mark style="color:$primary;">**conversation ID**</mark> of the chat you used to test <mark style="color:$primary;">**Brainy**</mark>.

To copy the conversation ID, click on the **vertical ellipsis** (the three dots) in the top right corner of the chat, and select the **`Copy conversation ID`** option from the dropdown menu.

<figure><img src="/files/SDGaaAkHuLrr48Ii0Ob0" alt=""><figcaption></figcaption></figure>

***

## Frequently Asked Questions

1. **Is&#x20;**<mark style="color:$primary;">**Brainy**</mark>**&#x20;free?**\ <mark style="color:green;">**Yes**</mark>, during the alpha phase.
2. **Can it deploy infrastructure?**\ <mark style="color:$danger;">**No**</mark>. It only supports <mark style="color:$primary;">**`plan`**</mark> and <mark style="color:$primary;">**`validate`**</mark>**.**
3. **Does it access the internet?**\
   No, but it has built-in knowledge of public modules.
4. **Can it make mistakes?**\
   Yes. You can:
   1. Ask it to fix issues.
   2. Revert using conversation checkpoints.
5. **Which cloud providers are supported?**\
   All providers supported by Brainboard (AWS, Azure, GCP, etc.)


# Left Pane

### Overview

The left pane is where all the graphical objects are available for you to use in the design area. You can also do the following:

* Select a specific cloud provider from the supported ones.
* Set the version of the selected cloud provider.
* Switch between Terraform/OpenTofu resources and data sources.

Once you select a cloud provider of your choice, the **left pane's** graphical object categories are refreshed to show the relevant design elements.

For example, if you select **GCP** (Google Cloud Platform), then ***AlloyDB*** appears under **Database** as a design element with other relevant options. However, if you select **Microsoft Azure** as your cloud service provider, then **MYSQL, CosmosDB** and other relevant database options are populated as design elements.

{% hint style="info" %}
**Custom Brainboard sections:** Custom design elements options are also available, such as **Containers** and **Modules**.
{% endhint %}

{% tabs %}
{% tab title="Azure" %}

<figure><img src="/files/Aq9soVjonuG6EuZuGoVB" alt="" width="247"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="AWS" %}

<figure><img src="/files/yUdSwsJtxEI4QTZ9PsAA" alt="" width="241"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="GCP" %}

<figure><img src="/files/RICN3pkjncSVnU5W4Us0" alt="" width="242"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Components of the left pane

Please refer to the image shared below to have a look at the main components on the left pane. Explanation is provided below it.

<figure><img src="/files/shNj9oT0qBJKLE4MSqX8" alt="" width="260"><figcaption></figcaption></figure>

1. **Cloud providers selector:** It allows you to select the cloud provider to use in the current architecture.

{% hint style="info" %}
The **"Custom configuration"** button under it allows you to customize the **Terraform/OpenTofu** provider block, as demonstrated in the image shared below.
{% endhint %}

<figure><img src="/files/WOSQ0UtnRaqADHR3hVCc" alt=""><figcaption></figcaption></figure>

2. **Cloud provider version:** This is the **Terraform/OpenTofu** version of the selected provider.

{% hint style="info" %}

* Brainboard automatically update the left pane whenever there is a new Terraform/OpenTofu version of the provider.
* When you select a version, the left pane will be updated for you to reflect the resources available in this specific version.
  {% endhint %}

3. **Resource type selector:** It allows you to switch between cloud resources and data sources.

{% hint style="info" %}
When you select a resource type, the left pane will be updated accordingly to reflect the resources available within the selected resource type.
{% endhint %}

4. **Search bar:** It allows you to search resources by:
   1. Full Terraform name, like *<mark style="color:$primary;">azurerm\_virtual\_network,</mark>* *<mark style="color:$primary;">aws\_vpc</mark>* <mark style="color:$primary;">or</mark> *<mark style="color:$primary;">google\_compute\_network</mark>*.
   2. Abbreviations.
   3. Part of the word.
5. **Buttons** to easily access the configuration of **variables, locals and outputs.**
6. **An arrow** option to **collapse or expand** the left pane.
7. **Category of resources:** It contains all the resources that belong to the same category as specified by the cloud providers.

{% hint style="info" %}
Every item is a sub-category, so you need to click on it to see all its resources.
{% endhint %}

### How to use these elements in your design?

To build your cloud infrastructure, you can **drag and drop** resources from the left pane into your design space, and then you can set up their cloud configuration.


# Cloud resources

### Overview

A Cloud resource is a building block of any architecture in Brainboard and could be one of the following:

1. Any resource available at the cloud provider that has either a Terraform resource or data source associated with it.
2. Terraform module.
3. Brainboard reference object that doesn't have a Terraform equivalent resource, but helps you build accurate architecture and generate a correct Terraform code. For example, *<mark style="color:$primary;">Containers</mark>* like *<mark style="color:$primary;">Azure location, AWS region</mark>*.

### Characteristics of a Cloud Resource

{% hint style="success" %}
It can be dragged & dropped from the [left panel](/cloud-design/left-bar).
{% endhint %}

{% hint style="success" %}
It has a lifecycle associated with it, so it can be created, updated and deleted.
{% endhint %}

{% hint style="success" %}
It has a set of configuration parameters that you can customize through the **Resource Configuration** panel.

🔗 Refer to the [Resource Configuration](/cloud-design/right-panel/resource-configuration) page for more information on how to configure a cloud resource.
{% endhint %}

### Types of cloud resources

Brainboard supports all the Terraform/OpenTofu resource types.

#### Resources

For a specific cloud provider, these represent all the resources available at any selected version of the Terraform provider.

#### Data sources

Data sources allow you to reference existing resources and access their information in a read-only mode.

#### Switching between resource types

You can switch between the data types and resources in two ways:

1. **From the left panel**\
   Select either the *<mark style="color:$primary;">resource</mark>* or *<mark style="color:$primary;">data source</mark>* option as demonstrated below.

{% columns %}
{% column width="50%" %}

<figure><img src="/files/l4hecThGGuyM2rK6C4E9" alt="" width="499"><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="50%" %}

<figure><img src="/files/kCn0PuUi5FMGYCcMDa0i" alt="" width="492"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

2. **Inside the design area:** If you want to switch any *<mark style="color:$primary;">resource</mark>* into *<mark style="color:$primary;">data</mark>* or vice-versa, right-click on the resource and select either `Switch to data` or `Switch to resource.`

<div><figure><img src="/files/xC3zDTesEgjgIa6SScIS" alt=""><figcaption></figcaption></figure> <figure><img src="/files/rxSJRY6VfQ2qG8ctZoDN" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
When you switch a resource into data, Brainboard automatically does the following:

* Changes all the references of this resource in the **Terraform code** into a **data block.**
* Updates the configuration in the **Resource Configuration** panel.
  {% endhint %}

### **Agnostic nodes**

{% hint style="info" %}
Nodes like **Texts, generic icons** or **graphical shapes** have no cloud configuration and will not be deployed into any cloud provider. These are diagramming objects only to help you represent information that cannot be represented by code.
{% endhint %}

#### Converting Cloud resource into an Icon

You can convert any cloud resource into an icon by right-clicking on the resource and choosing the option `Omit from code`.

{% hint style="warning" %}
Once a Cloud resource is converted into an icon, its Terraform code is also removed.
{% endhint %}

<figure><img src="/files/SZEurHvNJwpNG9EojndA" alt="" width="485"><figcaption></figcaption></figure>

#### Converting an icon into a Cloud resource

You can change an icon back into a cloud resource by right-clicking on the icon and choosing the option `Add to code`.

{% hint style="success" %}
When an icon is converted back to a cloud resource, its original configuration is restored, and its Terraform code is shown as well.
{% endhint %}

<figure><img src="/files/UO7WoeJC9qmM0f5SqniQ" alt="" width="440"><figcaption></figcaption></figure>

### Terraform modules

These are special cloud resources as they are <mark style="color:$primary;">containers</mark> and abstract a group of cloud resources.

In the **left panel,** there is a section where you can import your modules and access a modules' *<mark style="color:$primary;">Catalog</mark>* to manage them.

<figure><img src="/files/GbKlk2vv6hDx0IURfMkL" alt="" width="331"><figcaption></figcaption></figure>

{% hint style="info" %}
Please refer to the [Node documentation](/cloud-design/design-area/node) to understand **visual indications** and how cloud resources behave in the design area.
{% endhint %}

### Import module

{% hint style="success" %}
Brainboard supports all types of **Terraform modules** from any source.
{% endhint %}

To import your module, click on the `Import` button under **Modules** in the **left panel.** It will open the **"Import Terraform module"** window that allows you to specify information about the module.

<figure><img src="/files/GekEJmUPj4aIjAyn9Rvb" alt=""><figcaption></figcaption></figure>

#### Import module from registry

You can import your **Terraform / OpenTofu** modules from your <mark style="color:$primary;">Terraform registry</mark>, which could be **public** or **private**. You need to specify:

1. **The name of the module:** this will be used as a Terraform resource name when you use the module later. If needed, you can customize it for every module in the Resource Configuration panel when you use the module.
2. **The source path:** The path of the module in the registry.
3. **The version:** You can specify the version you want to import or keep the latest and later change it in the <mark style="color:$primary;">Resource Configuration</mark> panel when you use it.

<figure><img src="/files/vyFXugAte6sdV8PVxiHT" alt="" width="563"><figcaption></figcaption></figure>

1. <mark style="color:$primary;">**Importing from a private registry**</mark>

To import from a private registry, click on the toggle button `Use terraform registry credentials` below the **source path**, select the credentials of the registry.

2. <mark style="color:$primary;">**Importing from Git repository**</mark>

You can also import your Terraform / OpenTofu modules from any Git repository, **public** or **private.**

<figure><img src="/files/eOliWfVL6ohz9cbbUxHb" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
**GitHub/GitLab browser URL**

The source of the module can be the browser URL to the folder or repository hosting the module.

For GitHub and GitLab you can use the following format: *`git::https://github.com/org/repo//folder$ref=branch`*
{% endhint %}

{% hint style="info" %}
**Private repository**

If your repository is private, click on the switch button `My repo is private and requires credentials`, and specify the git credentials that will be used to import your module.
{% endhint %}

{% hint style="info" %}
**Custom source**

If you want Brainboard to generate a custom source string when the Terraform code is generated for the module, click on the switch button `Use a custom source in Terraform definition`.

This means that Brainboard will still use the git URL to fetch the latest information about the module, while the code generated matches the path that you specify in the source.

For example, you want to specify a local path in the module like `./modules/myModule` because it will be run by your **CI runners** that don't have access to your git but have the module local to the file system.
{% endhint %}

<figure><img src="/files/q6UrYpWvEuLUS2MDdFs0" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/sMqGdb3rw9bed54xPOqX" alt=""><figcaption></figcaption></figure>

3. <mark style="color:$primary;">**Importing from files**</mark>

This option allows you to upload your local Terraform files and create a module from them.

{% hint style="info" %}
You can customize the **icon** of your modules when you import them, regardless of the actual source.
{% endhint %}

{% hint style="warning" %}
When you initiate the import, Brainboard first checks if the Terraform code of the module is correct or not and displays an error if the module contains any Terraform errors or invalid syntax.
{% endhint %}

<figure><img src="/files/fY4pR35iy3Ug0vUDwhn4" alt="" width="563"><figcaption></figcaption></figure>

### Modules catalog

When you import your modules into Brainboard, you build a catalog of modules that anyone within the team can browse and use. It encourages the culture of reuse.

To access this catalog, click on the `Catalog` button under **Modules** in the **left panel.** It will open the gallery.

<figure><img src="/files/rZwxN6nKG8Tl3tXDx00Y" alt=""><figcaption></figcaption></figure>

#### **Modules Catalog Popup Window**

You can find the following options on the **Module Catalog** popup window:

1. **Search bar.**
2. **Pinned visibility button:** It helps you select/unselect only modules that are pinned in the current architecture.
3. **Global actions:** You can select all the modules of the catalog and apply bulk actions such as:
   1. **Pin:** It adds all the selected modules to the left panel, so even if you switch architectures, the modules stay available.
   2. **Unpin:** It removes all the selected modules from the left panel, but doesn't delete them.
   3. **Delete:** Deletes all the selected modules from Brainboard.
4. **Module's card:** This will contain all the information about the module.
5. **Pin/unpin the module:** It adds/removes a specific module to/from the left panel.
6. **Edit module:** Helps you edit the information of the module. It will open the same configuration window as the[#import-module](#import-module "mention").
7. **Delete module:** It permanently deletes the module from Brainboard.

{% hint style="danger" %}

* Deleting a module is a non-reversible action. You need to reimport any module that you delete if you want to reuse it.
* If the module is used in any architecture, when you delete it, the Terraform plan will fail, as Brainboard will cease access to it.
  {% endhint %}

### Terraform code

When you add a module to the design area, the initial Terraform code generated will contain the following.

{% hint style="success" %}
The **name of the module** as a resource name. Brainboard replaces any white space with `_` to generate a valid Terraform code.
{% endhint %}

{% hint style="success" %}
Only the **source field** is added, and if you defined a custom path, it will be used instead.
{% endhint %}

{% hint style="success" %}
If you keep the **latest version** of the module during import, Brainboard will not add the field `version` to the generated code, as Terraform will by default assume it is the latest.
{% endhint %}


# Input & output

### Overview

When you design your cloud infrastructures in <mark style="color:$primary;">**Brainboard**</mark>, the <mark style="color:$primary;">Terraform</mark> code is auto-generated for you based on the configuration of the resources.

{% hint style="info" %} <mark style="color:$primary;">**Brainboard**</mark> allows you to use **variables, locals** and **output** exactly as you would do it in **Terraform.**
{% endhint %}

{% hint style="success" %}
You can implement your naming conventions, set specific values for the configuration based on some criteria and define what information you want to display once the infrastructure is deployed.
{% endhint %}

<figure><img src="/files/SbAqC9cVr2CkEL6zGtJD" alt=""><figcaption></figcaption></figure>

***

### Related

{% columns %}
{% column width="25%" %} <a href="/pages/W8MHTry1DBE5oujGtKFH" class="button secondary" data-icon="memo-circle-check">Variables</a>
{% endcolumn %}

{% column width="25%" %} <a href="/pages/SG95HoEt14dRRLKPiBoz" class="button secondary" data-icon="memo-circle-check">Locals</a>
{% endcolumn %}

{% column width="49.999999999999986%" %} <a href="/pages/nCGFKLXWXCte44k83iGP" class="button secondary" data-icon="memo-circle-check">Output</a>
{% endcolumn %}
{% endcolumns %}


# Variables

### Variables

In **Terraform**, a variable is a way to store and reuse values throughout your **Terraform** code, and it is defined using the <mark style="color:$primary;">**`variable`**</mark> block.

{% hint style="info" %}
Brainboard allows you to create a variable **manually,** or you can also import it from an existing file. File types allowed are: <mark style="color:$primary;">**`tfvars`**</mark> , <mark style="color:$primary;">**`tf`**</mark>.
{% endhint %}

{% hint style="success" %} <mark style="color:$primary;">**Brainboard**</mark> follows **Terraform** best practices, so by default, when you create a new architecture, Brainboard automatically adds a variable called <mark style="color:$primary;">**`tags`**</mark> which is added in the generated **Terraform** code of every resource that supports tagging.
{% endhint %}

#### Action items on the Variables window

Shared below is the screenshot of the **Variables** window, numbered with action items/features available on this screen, followed by their brief description.

{% hint style="info" %}
By default, the variables list is displayed when you click on the **variables icon** in the right panel.
{% endhint %}

<figure><img src="/files/fV4cfgLLjI0Keb31IPCp" alt="" width="372"><figcaption></figcaption></figure>

<table><thead><tr><th width="57">#</th><th width="138">Feature</th><th width="563.6666259765625">Purpose / Description</th></tr></thead><tbody><tr><td><sub>1</sub></td><td><sub><strong>Add Variable</strong><strong> </strong><mark style="color:$primary;"><strong>(+)</strong></mark></sub></td><td><sub>To create a new variable. <em>(Explained in detail below).</em></sub></td></tr><tr><td><sub>2</sub></td><td><sub><strong>Search option</strong></sub></td><td><sub>To search for a specific variable on the Variables window. Keyword search is supported.</sub></td></tr><tr><td><sub>3</sub></td><td><sub><strong>Filter</strong></sub></td><td><sub>Using this option, you can filter the list of variables by scope or by the user who updated the variable. So, you have the following three options:</sub><br><sub>- <strong>All</strong> (no filter).</sub><br><sub>- <strong>Scope:</strong> architecture, environment, project, organization.</sub><br><sub><strong>- Updated by:</strong> select the user name whose updated variables you want to view.</sub></td></tr><tr><td><sub>4</sub></td><td><sub><strong>Sorting variables list</strong></sub></td><td><sub>You can sort the list of variables according to ascending or descending order of their names, as well as in ascending/descending order of the date when they were last updated.</sub></td></tr><tr><td><sub>5</sub></td><td><sub><strong>Filter</strong></sub></td><td><sub>The scope selector allows you to view variables that are defined in every scope or display all variables of all scopes.</sub></td></tr><tr><td><sub>6</sub></td><td><sub><strong>Expand all / Collapse all</strong></sub></td><td><sub>Clicking this will exapnd the variables section for you to view details of each variable in the list. Clicking it again will collapse the expanded view.</sub></td></tr></tbody></table>

#### Creating a new variable

To create a new variable, expand the right panel, and follow these steps:

1. Click the <mark style="color:$primary;">**`Variable`**</mark> icon available in the right panel.
2. Then, click the <mark style="color:$primary;">**`+`**</mark> icon to add/import variables. It opens the **Create** **Variable** modal.

<figure><img src="/files/FFxilFPplCRlpXnCALyA" alt=""><figcaption></figcaption></figure>

3. After that, you can either create a variable **manually** or you can click on the <mark style="color:$primary;">**`Import`**</mark> option to **import** already defined variables from an external file (<mark style="color:$primary;">**`tfvars`**</mark> , <mark style="color:$primary;">**`tf`**</mark> ).

<figure><img src="/files/0kMqeNV3GHLN1xK7ADRR" alt="" width="365"><figcaption></figcaption></figure>

On the ***"Create variable"*** form, you can specify the following information:

1. **Name of the variable:** This is the name that you'll use to reference the variable when you use it.

{% hint style="info" %}
It follows the naming conventions of **Terraform**; for example, it doesn't support spaces or starting with a number.

**Best practice:** use clear and explicit names and separate words with an underscore <mark style="color:$primary;">**`_`**</mark>.
{% endhint %}

2. **Scope:** You can set the level at which you want this variable to be available.

<figure><img src="/files/ZruYZ2XS7UhiosiViTGN" alt="" width="366"><figcaption></figcaption></figure>

{% hint style="info" %}
The four levels of scopes are listed in the order of **"least shared or restrictive to most shared/available/"**
{% endhint %}

{% hint style="info" %}
There is an override mechanism if the same variable is defined in multiple scopes.
{% endhint %}

<table><thead><tr><th width="175.66668701171875">Scope</th><th width="270.6666259765625">Explanation</th><th>Variable Override</th></tr></thead><tbody><tr><td><sub><strong>Architecture</strong></sub></td><td><sub>Variables that are defined with this scope are only available within this architecture only.</sub></td><td><sub>If the same variable is defined in another level as well, the default or values defined at the architecture level overrides any other level.</sub></td></tr><tr><td><sub><strong>Environment</strong></sub></td><td><sub>Variables defined at the environment level are available to all architectures within the same environment.</sub></td><td><sub>Variables defined in this level override those defined at project and organization level.</sub></td></tr><tr><td><sub><strong>Project</strong></sub></td><td><sub>Variables defined at the project level are available to all environments and architectures within the same project.</sub></td><td><sub>Variables defined in this level override those defined at the organization level.</sub></td></tr><tr><td><sub><strong>Organization</strong></sub></td><td><sub>Variables defined at the organization level are available to all architectures, environments and project within the organization.</sub></td><td></td></tr></tbody></table>

3. **Description:** It should concisely explain the purpose of the variable and what kind of value is expected. This description string might be included in documentation about the module, and so it should be written from the perspective of the user of the module rather than its maintainer.
4. **Variable type:** This allows you to restrict the type of value that will be accepted.

{% hint style="info" %}
If no type constraint is set, then a value of any type is accepted.
{% endhint %}

While type constraints are optional, we recommend specifying them; they can serve as helpful reminders for users of the module, and they allow **Terraform** to return a helpful error message if the wrong type is used.

{% hint style="success" %}
The supported type keywords are: <mark style="color:$primary;">**`any`**</mark> <mark style="color:$primary;">**`bool`**</mark> <mark style="color:$primary;">**`list`**</mark> <mark style="color:$primary;">**`map`**</mark> <mark style="color:$primary;">**`number`**</mark> <mark style="color:$primary;">**`object`**</mark> <mark style="color:$primary;">**`set`**</mark> <mark style="color:$primary;">**`string`**</mark> <mark style="color:$primary;">**`tuple`**</mark>
{% endhint %}

<figure><img src="/files/23yx6exH1DdRjJIiNhYK" alt="" width="370"><figcaption></figcaption></figure>

5. **Default value:** If present, the variable is considered to be *<mark style="color:$primary;">optional</mark>* and the default value will be used if no value is set.
6. **Value:** The value that will be used during **Terraform** execution and if defined, it overrides the default value.
   1. This value will be put in the file <mark style="color:$primary;">**`terraform.tfvars`**</mark> .
   2. If you convert the architecture into a template or clone the architecture, this value will be removed.
7. **Sensitive:** Setting this flag prevents **Terraform** from showing its value in the <mark style="color:$primary;">**`plan`**</mark> or <mark style="color:$primary;">**`apply`**</mark> output and <mark style="color:$primary;">**Brainboard**</mark> will store the variable in a separate vault.

{% hint style="warning" %}
Even if the variable is flagged sensitive, its value will still be stored in clear text in the **Terraform** state.
{% endhint %}

8. **Validation:** You can specify custom validation rules for the variable.

<figure><img src="/files/3QQoh4g9nUxrtmVL7fCb" alt="" width="368"><figcaption></figcaption></figure>

{% hint style="success" %}
For every variable defined, Brainboard creates a variable block in the file <mark style="color:$primary;">**`variables.tf`**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**.**</mark>
{% endhint %}

{% hint style="info" %}
Refer to the [RBAC (Role Based Access Control) documentation page](/settings/rbac) to understand how you can manage permissions to restrict/allow members and teams to add, update or delete variables.
{% endhint %}


# Locals

A **local value** assigns a name to an [expression](https://developer.hashicorp.com/terraform/language/expressions), so you can use the name multiple times within a module instead of repeating the expression.

{% hint style="success" %} <mark style="color:$primary;">**Brainboard**</mark> allows you to define multiple locals.
{% endhint %}

{% hint style="info" %}
When you define locals in **Brainboard**, they are added to the <mark style="color:$primary;">**`locals.tf`**</mark> file and in the same block <mark style="color:$primary;">**`locals`**</mark>
{% endhint %}

{% hint style="warning" icon="hand-point-right" %}
*The table of locals is similar to the table of* [*variables*](/cloud-design/left-bar/input-and-output/variables)*. Please refer to it to understand the different components of the user interface.*
{% endhint %}

#### Creating a new local

1. Click the <mark style="color:$primary;">**`Locals`**</mark> icon available in the right panel.
2. Then, click the <mark style="color:$primary;">**`+`**</mark> icon to add/import variables. It opens the **Create local** modal.
3. Specify the *<mark style="color:$primary;">Name</mark>, <mark style="color:$primary;">Description</mark>* and *<mark style="color:$primary;">Value</mark>* of the local.

<figure><img src="/files/MfCG9dCKdA9xuUzlobu5" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you are using a complex expression in the value field, you need to quote it, as you can mix **strings, functions, and variables.**
{% endhint %}


# Output

**Output values** make information about your cloud infrastructure available on the **command line** and will be displayed in the output of execution.

{% hint style="warning" icon="hand-point-right" %}
*The table of outputs is similar to the table of* [*variables*](/cloud-design/left-bar/input-and-output/variables)*. Please refer to it to understand the different components of the user interface.*
{% endhint %}

#### Creating an output

1. Click the <mark style="color:$primary;">**`Outputs`**</mark> icon available in the right panel.
2. Then, click the <mark style="color:$primary;">**`+`**</mark> icon to add/import variables. It opens the **Create output** modal.
3. Specify the *<mark style="color:$primary;">Name</mark>, <mark style="color:$primary;">Description</mark>* and *<mark style="color:$primary;">Value</mark>* of the output.

<figure><img src="/files/9jBBnquOUjoRtRilhPAc" alt=""><figcaption></figcaption></figure>

4. You can also specify if the output is **sensitive**, has a **dependency**, or has a **precondition.**

<figure><img src="/files/L6laDiOtH3iSL8MvC4Aj" alt="" width="370"><figcaption></figcaption></figure>

{% hint style="success" %}
For every output defined, <mark style="color:$primary;">**Brainboard**</mark> creates an output block in the file <mark style="color:$primary;">**`outputs.tf`**</mark>.
{% endhint %}


# Design area


# Node

### Overview

The node is the graphical object you use to build your cloud infrastructure and is the building block of the architecture.

{% hint style="success" %}
When you drag and drop a **node** from the left panel into the design area, you can customize both its graphical aspects and its cloud configuration to generate its Terraform code.
{% endhint %}

***

### Types of nodes

#### **1. Resource**

It represents a cloud resource for a given provider for which Brainboard generates the `resource` Terraform block.

<figure><img src="/files/5D5iw1AJdKBwUI4tvLq2" alt="" width="375"><figcaption></figcaption></figure>

#### **2. Data source**

This is a read-only object that allows you to reference an existing cloud resource. Brainboard generates the `data` Terraform block for it.

The data block is indicated with a cube on its left.

<figure><img src="/files/O4HbEFwaZKcswuMPtL61" alt="" width="375"><figcaption></figcaption></figure>

#### **3. Icon only**

This object is used to depict a graphical component that doesn't have a Terraform code, but has a meaning in the architecture.

<figure><img src="/files/dHLgUOfoKfQ5T2JbSm4Z" alt=""><figcaption></figcaption></figure>

#### **4. Container**

This node is supposed to contain other resources and pass some of its cloud or graphical configurations to its children.

1. **Azure example**

When you add an **AKS cluster** to the resource group, it automatically inherits the `resource_group_name` from the RG.

<figure><img src="/files/x0x2QWAGpbE5wWSVAlnR" alt=""><figcaption></figcaption></figure>

2. **AWS example**

When you add an internet gateway to the VPC, it inherits the `vpc_id` automatically from the VPC.

<figure><img src="/files/QiH45uCPEgIXx2A0F1KD" alt=""><figcaption></figcaption></figure>

3. **GCP example:** When you add compute firewall into a compute network, it inherits its `network` automatically

<figure><img src="/files/49WjMCzvLxU90GOdUlGO" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Brainboard group**

* This is a special container of resources that has a title and icon that you can customize.
* It supports nested containers.

<img src="/files/Mepj1ZZUr8G5jTqJE3G4" alt="" data-size="original">
{% endhint %}

4. **Module**

This node represents a Terraform module for which Brainboard generates a `module` block.

By default, when you can a module, it is represented by a simple node containing the icon of the provider of the resources

<figure><img src="/files/veytj62gCD51esvbocm9" alt=""><figcaption></figcaption></figure>

You can change any module into a container, by right-clicking on it and select `Switch to container.` You can turn it back into a node by right click and select `Switch to node`.

<figure><img src="/files/ICslluVoqX862LeiK5Op" alt="" width="488"><figcaption></figcaption></figure>

5. **Shape**

This is a pure graphical object that helps you depict information that don't have a Terraform code.

Some shapes can also be containers, like rectangles and circles, which helps you group your resources without triggering cloud configuration inheritance.

<figure><img src="/files/cbbl2tl5BLj1Kc61rE4m" alt="" width="329"><figcaption></figcaption></figure>

6. **Text**

This node helps create a text object to add complementary information to your cloud architecture.

***

### Graphical options

#### Options bar

The following graphical options are common to any node in the design area.

<figure><img src="/files/HWXTGJT4hT2nqFyOkZoZ" alt=""><figcaption></figcaption></figure>

1. **Order:** Change the z-index of the node.

<figure><img src="/files/yIKhsK4vOPeAYoMl5cBM" alt="" width="447"><figcaption></figcaption></figure>

<table><thead><tr><th width="74.48138427734375">#</th><th width="203.13238525390625">Oorder</th></tr></thead><tbody><tr><td>a</td><td>Send backwards</td></tr><tr><td>b</td><td>Send to back</td></tr><tr><td>c</td><td>Bring to front</td></tr><tr><td>d</td><td>Bring forward</td></tr></tbody></table>

<table><thead><tr><th width="74.48138427734375">#</th><th width="203.13238525390625">Oorder</th></tr></thead><tbody><tr><td>a</td><td>Send backwards</td></tr><tr><td>b</td><td>Send to back</td></tr><tr><td>c</td><td>Bring to front</td></tr><tr><td>d</td><td>Bring forward</td></tr></tbody></table>

2. **Align:** This option allows you to align multiple nodes. You must select all the nodes that you need to align.

<figure><img src="/files/UPVP87mMm3NBcCGNX9oU" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="74.48138427734375">#</th><th width="477.2064208984375">Alignment</th></tr></thead><tbody><tr><td>a</td><td>Align nodes left</td></tr><tr><td>b</td><td>Align vertically nodes' centers</td></tr><tr><td>c</td><td>Align nodes right</td></tr><tr><td>d</td><td>Align nodes to the top</td></tr><tr><td>e</td><td>Align horizontally nodes' centers</td></tr><tr><td>f</td><td>Align nodes on the bottom</td></tr><tr><td>g</td><td>Distribute space between nodes vertically</td></tr><tr><td>h</td><td>Distribute space between nodes horizontally</td></tr><tr><td>i</td><td>Tidy up nodes</td></tr></tbody></table>

3. Change the **background colour** of the node.
4. Change the **text colour** of the node.
5. Change the **border colour** of the node.
6. Change the **border radius of the node.**
7. Make the **borders of the node dashed.**
8. Change the **border weight** of the node.
9. **Open cloud configuration:** This will open the **Resource Configuration** panel that contains all Terraform fields that you can fill. Brainboard generates the Terraform code based on this configuration.

***

#### Context menu

1. **Resource, data source and container**

These 3 types of nodes share the same options in their context menu.

<figure><img src="/files/7Gjx2fuREtU5kHTAzkqt" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="58.92578125">#</th><th width="684.6141357421875">Menu item</th></tr></thead><tbody><tr><td>a</td><td>Open the Resource Configuration panel to update the cloud configuration.</td></tr><tr><td>b</td><td>Switch the resource into data and vice versa.</td></tr><tr><td>c</td><td>Change the title of the node.</td></tr><tr><td>d</td><td>This allows you to lock/unlock the node graphically, which means it cannot be moved, resized, deleted or modified.</td></tr><tr><td>e</td><td>❓❓</td></tr><tr><td>f</td><td>Duplicate the node.</td></tr><tr><td>g</td><td>❓❓</td></tr><tr><td>h</td><td><p>Disable the Terraform code generation of the node without deleting it from the design</p><p>You can enable the code by right-clicking on the resource and choosing the option <code>Add to code</code></p></td></tr><tr><td>i</td><td>Delete the node from the design and the generated code.</td></tr></tbody></table>

2. **Module**

All the options are similar to the resource, except that for modules, you have the possibility to **switch a module visually into a container and switch it back into a normal node if needed.**

<figure><img src="/files/4uR9LvtrrELPrVrm8QZo" alt="" width="393"><figcaption></figcaption></figure>

***

### Cloud configuration

Every node that is a cloud resource will have its Terraform code automatically generated and updated when you fill in the information in the **Resource Configuration panel** or when you move the node into a parent, where it inherits some cloud properties.

{% hint style="info" %}
Refer to the [Resource Configuration](/cloud-design/right-panel/resource-configuration) page for more details about how to update the cloud configuration of nodes and all the options available.
{% endhint %}

***

### Behavior

Brainboard design area is a smart canvas that has <mark style="color:$primary;">**cloud knowledge**</mark> and is able to understand the relationships and links between resources.

Explained below is the behaviour of the node in the design area.

1. A <mark style="color:$primary;">node</mark> can be selected when you click on its **Terraform** code in the right pane.
2. <mark style="color:$primary;">Nodes</mark> can be linked to each other automatically when you reference a **Terraform** attribute from one node to another.

{% hint style="info" %}
The name of the field that references the other node is put in the text of the connector created between both resources.
{% endhint %}

3. <mark style="color:$primary;">Containers</mark> can pass their cloud properties to their <mark style="color:$primary;">children</mark> when **Terraform** supports it.

{% hint style="info" %}
Brainboard can detect what should be passed and how, and then generate the right code.
{% endhint %}

4. When you update the `resource name` of any <mark style="color:$primary;">node</mark> at any level, Brainboard automatically updates all the nodes that depend on it with the **new name.**
5. A <mark style="color:$primary;">container</mark> cannot be resized smaller than its children. It has to visually indicate the children contained.
6. There is <mark style="color:$danger;">**no**</mark> inheritance between resources of different providers.

{% hint style="info" %}
For example, you cannot add an `aws_subnet` inside `azurerm_virtual_network`.
{% endhint %}

7. Within the same provider, you <mark style="color:$danger;">**cannot**</mark> do what is not allowed by the provider.

{% hint style="info" %}
For example, you cannot add a subnet inside a subnet, VPC inside VPC, VNET inside VNET...
{% endhint %}

8. When you try to add a <mark style="color:$primary;">container</mark> into another one, Brainboard automatically fixes the right order of containers based on what is accepted by the provider.

{% hint style="info" %}
For example, if you try to add a VPC inside a subnet, Brainboard will put the subnet inside the VPC and fill the information correctly for you.
{% endhint %}

9. You can still reference resources from different providers in the **Resource Configuration** panel.

{% hint style="info" %}
For example, reference an AD user inside a VM.
{% endhint %}

10. When selecting multiple resources and cloning them, Brainboard automatically generates new resource names to avoid collisions and tracks dependencies correctly. Which means the Terraform plan should pass after the **clone.**


# Connectors

### Overview

{% hint style="info" %}
A connector is a line that connects two resources in the architecture. It is used to show a relationship between two resources.
{% endhint %}

*This article covers information about different connector types and how to create, edit, and delete a connector.*

***

### Connector types

There are two types of connectors:

1. Visual connector
2. Relationship connectors

#### **1. Visual connectors**

These are used to show a visual relationship between two resources. They are represented by a solid line.

<figure><img src="/files/daMJ3CbsA17X74zIp2VI" alt="" width="563"><figcaption></figcaption></figure>

#### **2. Relationship connectors**

These are used to show a relationship between two resources. They are represented by a solid line with the corresponding text in the middle of the connector.

<figure><img src="/files/bZklCsqeGBC268ixaD9e" alt="" width="558"><figcaption></figcaption></figure>

***

### How to create a connector?

#### Creating a visual connector

To create a **visual** connector, you need to follow these steps:

1. Click on the node/resource that you want to connect to another node/resource.
2. Once the borders of the selected node/resource are highlighted, you will see a **small circle** in the middle of all its four borders. Hover over that small circle, and you will see an **arrow-shaped icon**. Click on that arrow-shaped icon, drag it to another node/resource to which you want to connect the first node/resource, and drop it there. You can now see a visual connector connecting the two nodes/resources in your design space.

<figure><img src="/files/hjdRPoHPyNmTfeyqkp7y" alt=""><figcaption></figcaption></figure>

#### Creating a relationship connector between resources

To create a relationship connector, you need to follow these steps:

1. Right-click on the resource and select `Edit config` from the context menu.

<figure><img src="/files/s6XB699A5qRX7cyFBWEl" alt="" width="422"><figcaption></figcaption></figure>

2. The selected resource's **form will** open in the right pane. You can scroll down to its **Main parameters** and look for the relevant field where you can select the other resource for connection.

For example, in the image shared below, the desired storage is selected under the field **`Storage Account Name`** for the *<mark style="color:$primary;">Linux function app</mark>*.

{% hint style="success" %}
Once you select the desired resource in the relevant field, a relationship connector is drawn from the first resource pointing toward the second. The connector line will also be labelled accordingly.
{% endhint %}

<figure><img src="/files/q0sTPUTiZJVXIbVJEjtN" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To verify the connection/relationship, you can cross-check the **label text** with the corresponding value in the code.
{% endhint %}

***

### How to delete a connector?

To delete a connector, simply click on the **connector line** and hit the **`Delete`** key on your keyboard. Or, you can click the **bin icon** available in the connector editor bar that appears upon clicking the connector line.

<figure><img src="/files/3cmPTatiOoXJLTmYY0Tn" alt=""><figcaption></figcaption></figure>

You will be prompted with two options:

* **Keep reference:** Clicking on this will only delete the *<mark style="color:$primary;">visual connector line</mark>*, while the configured relationship between the resources will stay **intact.**
* **Remove the reference:** Clicking on this will delete the *<mark style="color:$primary;">visual connector line</mark>* as well as the configured *<mark style="color:$primary;">relationship</mark>* between the resources.

<figure><img src="/files/XHGD3mfm7LlJuclC8x3J" alt=""><figcaption></figcaption></figure>

### How to edit a connector?

To edit a connector, simply click on the connect, and the options bar will appear above it. You can customzie the following properties of a connector-line:

* **Connector type:** Available options are **`orthogonal`**, **`straight`**, and **`curvy`**.
* **Line style:** Available options are **`solid`**, **`small dash`**, **`medium dash`**, and **`large dash`**.
* **Colour:** You can use the available colour palette or enter a specific hex code.
* **Line weight:** You can define the connector line weight as **`small`**, **`medium`**, or **`large`**.
* **Start/end shape options:** These options enable you to define the start and the end shape of the connector line. Available options are `filled arrow`, `outlined arrow`, `no shape`.

<figure><img src="/files/JWf2utEnpS7HqC7ea3UP" alt=""><figcaption></figcaption></figure>

### How to edit the connector text?

To edit the connector label text, simply **`double-click`** on the connector line and it will become editable as the **`cursor`** will appear at the end of the text. You can then edit it as you wish.

<figure><img src="/files/Y7N6uh937orzrEmTGOK6" alt=""><figcaption></figcaption></figure>


# Inheritance


# Connection between resources


# Versioning

### Overview

Brainboard provides a native versioning mechanism that allows you to **keep track** of your changes and **rollback/restore** any specific point-in-time version.

*This article lists the information that is saved for each version in Brainboard, in addition to steps for creating a new version, viewing already saved versions and restoring an existing version.*

***

### Components of a version

When you create a version, Brainboard saves the following information:

✅ The architecture design.

✅ The version of the cloud provider selected to create the architecture.

✅ Variables.

✅ Output.

✅ The README file.

✅ The structure of the Terraform files.

✅ Timestamp in UTC when the version is created.

✅The person who created the version.

✅ The commit message.

{% hint style="info" %}
The Terraform code is automatically generated, and it is not saved as code.
{% endhint %}

***

### How to create a version?

To create a version of your architecture, you can follow these steps:

1. Click on the version history icon in the top navigation bar. The <mark style="color:$primary;">**Version history**</mark> will open in the right pane.
2. Click the <mark style="color:$primary;">**`New version`**</mark> button on the <mark style="color:$primary;">**Version history**</mark> pane.

<figure><img src="/files/Ex6It7TTxcMvFv8anlZP" alt=""><figcaption></figcaption></figure>

3. On the **Create new version** popup modal, you can enter the description of the version and click <mark style="color:$primary;">**`Create`**</mark> to save.

{% hint style="info" %}
The version description could be the same commit message you would write when performing a **pull request**. You can write multiline text if you want to provide more details.
{% endhint %}

<figure><img src="/files/bCcIUQox1u2bfmQVpqdg" alt=""><figcaption></figcaption></figure>

4. When a version is created and saved, it's listed on the <mark style="color:$primary;">**Version history**</mark> pane on the right side.

{% hint style="success" %}
Each new version that's created also displays the **name of the user** who created along with the **time/date** it was created.
{% endhint %}

<figure><img src="/files/zXtptgOiIGuWCkJ21CAn" alt=""><figcaption></figcaption></figure>

***

### View available versions

If you want to view the list of available versions of your architecture design, click on the **version history icon** in the top navigation bar. The **Version history** pane will expand on the right side of the screen.

{% hint style="info" %}
The versions are listed in order of **latest/newest** to **oldest.**
{% endhint %}

<figure><img src="/files/6EMU7vXkSTJNiexsnKkY" alt=""><figcaption></figcaption></figure>

***

### How to restore a version?

To restore any version, click on the **version history icon** in the top navigation bar. On the **Version history** pane on the right side, click on the **version** you want to restore. The clicked version will be restored, and the following success message will be displayed at the bottom of the **Version history** pane.

*<mark style="color:green;">Architecture version restored successfully.</mark>*

<figure><img src="/files/0BQ9zGYaLH8Jqlhj5J67" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**IMPORTANT**

* Brainboard versions are immutable snapshots of your infrastructure. You cannot delete them.
* You can check out any version and work on it without altering the history of the versioning.
* When you clone an architecture or create a template from it, its versions will be removed.
* When you checkout a version, both the diagram and the Terraform code will be updated.
  {% endhint %}

***

### Push to git

Please refer to the [<mark style="color:$primary;">**`Pull requests`**</mark>](/cloud-design/autogenerated-code/pull-requests) page for detailed information on how to do pull requests and save the generated code into git.


# Documentation


# Collaboration / Multi-user


# Graphical options

## Overview

Brainboard graphical elements within the design area help you control the visual of some aspects of the interface or display useful information.

There are four groups of graphical options:

1. **Options bar:** It contains options that allow you to control the graphical options that are not related to a node, like the grid, the zoom, etc.
2. **Templates button:** It opens the templates catalog, where you can see the available cloud architecture templates and use them.
3. **Nodes number:** Shows either the number of nodes that are selected or present in the design area when no node is selected.
4. **Groups:** This button allows you to list & update all nodes' groups / Terraform files.

***

## 1. Options bar

<figure><img src="/files/xMiU6It7XaMQ42vCeHgT" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="56.40740966796875" data-type="number">#</th><th width="176.370361328125">Feature</th><th width="512.2434692382812">Description</th></tr></thead><tbody><tr><td>1</td><td><strong>Select/Grab Mode</strong></td><td><p>Using this option you can switch between select and grab modes.</p><ul><li><strong>Select</strong> mode <mark style="color:$primary;">(arrow icon)</mark> allows you to select resources and interact with them</li><li><strong>Grab</strong> mode <mark style="color:$primary;">(hand icon)</mark> allows you to move the canvas.</li></ul></td></tr><tr><td>2</td><td><strong>Zoom in</strong></td><td><p>It <mark style="color:$primary;">zooms in</mark> on the design area using its center as the zoom point.</p><p>⇒ You can also use the <strong>CTRL + mouse scroll</strong> to zoom in the canvas.</p></td></tr><tr><td>3</td><td><strong>Fit content</strong></td><td>It centralizes the resources present in the design area in the middle, where all nodes are visible.</td></tr><tr><td>4</td><td><strong>Zoom out</strong></td><td><p>It <mark style="color:$primary;">zooms out</mark> the design area using its center as the zoom point.</p><p>⇒ You can also use the <strong>CTRL + mouse scroll</strong> to zoom out the canvas.</p></td></tr><tr><td>5</td><td><strong>Undo</strong></td><td>Reverses the changes.</td></tr><tr><td>6</td><td><strong>Redo</strong></td><td>Restores the changes.</td></tr><tr><td>7</td><td><strong>Sync information</strong></td><td>This button opens the window that shows you architectures that are synced with the currently opened architecture design.<br><img src="/files/Snv9uzSvRbhpFDUyuyrc" alt=""></td></tr><tr><td>8</td><td><strong>Export architecture</strong></td><td><p><strong>A.</strong> Using this option, you can either download your diagram as</p><p>a <mark style="color:$primary;">PNG, SVG</mark> or <mark style="color:$primary;">PDF</mark> file.</p><p>You can also include the background grid in the download or set a transparent background.</p><p><br><img src="/files/9A9FeK1oqNpn8TF7lAeB" alt=""><br><br><strong>B.</strong> Or, you can also export your file in Brainboard format<mark style="color:$primary;"><strong>(JSON)</strong></mark>.</p><p>⇒ You can share the <mark style="color:$primary;"><strong>JSON</strong></mark> file with someone else or restore it in a different organization, it will create the architecture exactly as it is with its Terraform code, variables, output and ReadMe file.</p></td></tr><tr><td>9</td><td><strong>Version history</strong></td><td>Show architecture versions. Refer to the <a href="/pages/krKYw7p1F7BFbQkc7BOg#list-versions">versioning page</a> for more details about how to list versions and how to restore a specific one.</td></tr><tr><td>10</td><td><strong>Grid view options</strong></td><td>Available options for grid view are: <mark style="color:$primary;">Dots</mark>, <mark style="color:$primary;">Lines</mark>, and <mark style="color:$primary;">Hide</mark>.</td></tr><tr><td>11</td><td><strong>Node view options</strong></td><td><p>You can configure the node design using the options available in this drop-down menu. You can <strong>enable/disable</strong> the following for the nodes in your design.</p><ul><li>Show titles</li><li>Show connectors</li><li>Show connector labels</li><li>Animate connector line</li><li>Animate connector circles</li></ul><p>⇒ These settings apply to all the nodes of the currently opened architecture diagram.<br><img src="/files/8jdvT85IxGH6LKCb8x4j" alt=""></p></td></tr><tr><td>12</td><td><strong>Readme</strong></td><td><p>This opens the <mark style="color:$primary;">README</mark> of the architecture, where you can update its content.</p><p>⇒ This file will be included in the list of the files to push to git when you perform a <strong>pull request</strong>.<br><img src="/files/1BhqMkQ3SFIEFd6XJAQa" alt=""></p></td></tr></tbody></table>

{% hint style="info" %}
**Universal Undo/Redo**

Brainboard uses the backend as a store for undo and redo actions, which means, even if you reload your page, close & reopen the browser or even connect from a different computer, you can undo & redo your actions.
{% endhint %}

***

## 2. Templates button

It allows you to open the templates catalog window, where you can see the public and private templates.

<figure><img src="/files/Mw4ps8CPaP8z2DsNikdL" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Mw4ps8CPaP8z2DsNikdL" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Refer to the [template catalog](/data/data-structure/template) page for detailed information about how to use it.
{% endhint %}

***

## 3. Number of nodes

This button is located in the bottom-left corner of the architecture, and it shows the number of nodes in the architecture.

<figure><img src="/files/AnaBAeqk3plrp6QwuO2y" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/AnaBAeqk3plrp6QwuO2y" alt=""><figcaption></figcaption></figure>

#### Selected nodes

When you select more than one node at a time, for example, when you select multiple nodes to group them, then the <mark style="color:$primary;">**total number of currently selected nodes**</mark> is displayed instead of all the nodes available in your architecture design.

For instance, two nodes are selected in the screenshot shared below.

<figure><img src="/files/hJe6pzeHgTYYAoqoGVui" alt=""><figcaption></figcaption></figure>

***

## 4. Groups

You can group <mark style="color:$primary;">**nodes,**</mark> and they will also be moved to the same Terraform file.

The hamburger-icon button located in the bottom-right corner of the design area displays all the groups you have in the currently opened architecture design

<figure><img src="/files/j4I2FL6kqcxIQTwZOe4B" alt="" width="563"><figcaption></figcaption></figure>

1. **Show resources:** This will select and highlight all the nodes of the group in the design area. Then, you can apply bulk formatting to all the nodes of the selected group. For example, the two grouped nodes, the <mark style="color:$primary;">**`even_handler`**</mark> and the <mark style="color:$primary;">**`Dead Letter Queue`**</mark> in the screenshot shared below have a green border of the same width.

<figure><img src="/files/RrLHGunjUnPuehjsXI6z" alt=""><figcaption></figcaption></figure>

2. **Delete the group:** Clicking this will delete the group and put all its resources in the main file <mark style="color:$primary;">(main.tf)</mark>.

❗This action doesn't delete the resources.

{% hint style="info" %}
By default, all the nodes are listed/grouped in the main Terraform file, and this file cannot be deleted.
{% endhint %}

### How to group nodes?

To group any nodes, follow these simple steps:

1. Use the **drag and select (box select)** method, i.e., click and hold the left mouse button in an empty area near the first node, then drag a rectangle over the node(s) that you want to group with the first node.
2. Then, right-click over the selected nodes area, and click the <mark style="color:$primary;">**`Move to file`**</mark> option in the context menu.
3. On the <mark style="color:$primary;">**`Edit terraform file name`**</mark> popup modal, give a reasonable name to your group, and click <mark style="color:$primary;">**`Save`**</mark>.

<figure><img src="/files/JuohmfCWJj9xer3bru0O" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Once a group is created, it is listed among other groups in the file and can be accessed using the group button (the hamburger icon) available in the bottom right corner of your Brainboard canvas.
{% endhint %}


# Multi-cloud


# Provider specific configurations


# Right Panel

This article covers the information about the options/features available in the right panel, right panel controls, and best practices. You can also find links to the related articles at the end.

## Overview

The **Right Panel** in Brainboard provides quick access to your architecture's resources, generated code, validation issues, and deployment configuration. It serves as a central hub for reviewing, configuring, and managing your cloud infrastructure.

***

## Panel Controls

### Collapsing/expanding the Panel

Click the **arrow icon** at the top of the panel to collapse/expand it.

<figure><img src="/files/xBlvB0UZs3MR2WnXcUCm" alt="" width="511"><figcaption></figcaption></figure>

### Keyboard Shortcuts

* `SHIFT+CMD+D` / `SHIFT+CTRL+D` - Toggle **Code** tab.
* `SHIFT+CMD+R` / `SHIFT+CTRL+R` - Toggle **Resources** tab.

### Resizing

Drag the **left edge** of the panel to resize its width according to your preference.

## Available tabs

The Right Panel features four main tabs, each serving a specific purpose:

1. [**Resources**](broken://pages/ew4sNtDnTiwht6exaLMs)**:** View and manage all resources in your architecture.
2. [**Code**](/cloud-design/right-panel/code)**:** View and edit generated Terraform code.
3. [**Issues**](/cloud-design/right-panel/issues)**:** Review architecture warnings and validation errors.
4. [**Deploy**](/cloud-design/right-panel/deploy)**:** Configure and monitor CI/CD deployment pipelines.

## Best Practices

* **Use the&#x20;**<mark style="color:$primary;">**Resources**</mark>**&#x20;tab** for quick parameter checks and navigation between resources.
* **Use the&#x20;**<mark style="color:$primary;">**Code**</mark>**&#x20;tab** when you need to make bulk changes or prefer code-first workflows.
* **Check the&#x20;**<mark style="color:$primary;">**Issues**</mark>**&#x20;tab** regularly, especially before running Terraform plan or apply.
* **Configure the&#x20;**<mark style="color:$primary;">**Deploy**</mark>**&#x20;tab** once and use it to maintain consistent deployment workflows.

***

## Related articles

* [Resources List](/cloud-design/right-panel/resources-list): Detailed resource management.
* [Resource Configuration](/cloud-design/right-panel/resource-configuration): Advanced resource configuration.
* [Code Edition](/cloud-design/code-edition): Code editing capabilities.
* [Design Area](/cloud-design/design-area): Visual diagram interface.


# Deploy

The **Deploy** tab provides access to Brainboard's deployment pipeline configuration and monitoring capabilities.

<figure><img src="/files/N8ZhXdlWvZ1Gm6kyRfz8" alt=""><figcaption></figcaption></figure>

### Key Features

* **Pipeline Configuration:** Set up and manage deployment workflows.
* **Environment Settings:** Configure deployment targets.
* **Execution History:** View past deployment runs and their status.
* **Quick Actions:** Trigger deployments directly from the panel

{% hint style="info" %}
Learn more about deployment in [CI/CD Designer](/automation/ci-cd-designer) and [Pipelines](/automation/pipelines).
{% endhint %}

***


# Code

The **Code** tab provides direct access to view and edit your auto-generated **Terraform** code. This feature is ideal for users who prefer code-centric workflows or need to make quick adjustments.

### Key Features

* **File Selector:** Switch between different **Terraform** files *<mark style="color:$primary;">(main.tf, variables.tf, outputs.tf, etc.).</mark>*
* **Syntax Highlighting:** Full Terraform HCL syntax support.
* **Code Validation:** Real-time validation with error reporting.
* **Keyboard Shortcuts**:
  * `CMD/CTRL+S` - Save changes.
  * `CMD/CTRL+F` - Search.
  * `CMD/CTRL+H` - Find and replace.
  * `CMD/CTRL+SHIFT+R` - Discard changes.

{% hint style="warning" %}
Changes made in the code editor are bidirectional - they update both the code and the visual diagram. However, some limitations apply to preserve Brainboard's structured approach.
{% endhint %}

{% hint style="info" %}
Learn more about code editing in [Code Edition](/cloud-design/code-edition).
{% endhint %}


# Issues

The **Issues** tab displays architecture warnings and validation errors, helping you maintain best practices and catch configuration problems early.

<figure><img src="/files/EeDGhdRf9Cbl3HsnwHdL" alt=""><figcaption></figcaption></figure>

### Key Features

* **Architecture Warnings:** Identifies potential configuration issues:
  * Missing required parameters.
  * Unconnected resources.
  * Security best practice violations.
  * Resource relationship inconsistencies.
* **Validation Errors:** Shows Terraform validation errors before deployment.
* **Quick Navigation:** Click any issue to navigate to the affected resource.

{% hint style="info" %}
Regular review of the **Issues** tab helps maintain infrastructure quality and prevents deployment failures.
{% endhint %}


# Resources

The **Resources** list provides a comprehensive overview of all cloud resources in your architecture, displayed as interactive cards. This interface enables quick navigation, parameter inspection, and resource management directly from the right panel.

<figure><img src="/files/NDmlpp94b6sr4IyaNsuz" alt=""><figcaption></figcaption></figure>

## Key User Goals

The **Resources List** is designed to help you:

1. **Find resources quickly:** Search and filter through all resources in your architecture.
2. **See resource overview:** View key parameters and configuration at a glance.
3. **Navigate to diagram:** Jump directly to any resource's location in the visual diagram.
4. **Understand relationships:** See how resources connect and reference each other.

{% hint style="info" %}
Each resource is displayed as a card. Learn more about [resource cards](/cloud-design/right-panel/resources-list/resource-cards).
{% endhint %}

***

## Search and Filter

### Resource Search

Use the search option at the top of the **Resources** to filter resources by:

* **Resource Name:** Search by the **Terraform** resource name.
* **Resource Type:** Filter by type (e.g., "storage", "network", "compute").
* **Parameters:** Find resources with specific parameter values.

{% hint style="info" %}

### Search Behavior

* Search is **real-time** - results update as you type.
* Search is **case-insensitive**
* Partial matches are supported
* Clear the search to see all resources again
  {% endhint %}

***

## View Modes

The **Resources** list supports two organizational modes:

### Dynamic View

This view displays all resources in a single continuous list, sorted by creation order or file assignment. It is ideal for:

* Smaller architectures (under 50 resources).
* Quick scanning of all resources.
* Finding resources by scrolling.

### File-Grouped View

This view organizes resources by their **Terraform** file assignment, with collapsible sections for each file. This view is ideal for:

* Larger architectures with many resources.
* Viewing resources by logical file organization.
* Understanding file structure.

{% hint style="info" %}
For architectures with many resources, **File-Grouped** View automatically activates to improve performance and navigation.
{% endhint %}

***

## Visibility States

The **Resources** list displays different messages when:

* **No Resources:** <mark style="color:$primary;">"Drop a resource on the canvas."</mark>
* **No Visible Resources:** When all resources are outside the visible canvas area, you'll see a <mark style="color:$primary;">**`Fit Content to View`**</mark> button.
* **No Search Results:** <mark style="color:$primary;">"No results found"</mark> message is displayed when no resource matches the searched text/keyword. In this case, you can clear the text/keyword in the search bar and try again.

***

## Related articles

* [Resource cards](/cloud-design/right-panel/resources-list/resource-cards): Information on card components, parameters display, and card actions.
* [Resource Organization](/cloud-design/right-panel/resources-list/resource-organization): Default, auto, and manual file assignment.
* [Best Practices and Shortcuts](/cloud-design/right-panel/resources-list/best-practices-and-sortcuts): Best practices for using the **Resources** list and keyboard shortcuts.
* [Resource Configuration](/cloud-design/right-panel/resource-configuration): Detailed resource configuration interface.
* [Right Panel](/cloud-design/right-panel): Overview of all right panel tabs.
* [Design Area](/cloud-design/design-area): Visual diagram interface.
* [Split Code into Files](/cloud-design/autogenerated-code/split-code-into-files): Organizing **Terraform** files.


# Resource Cards

## Card Components

Each resource card displays:

1. **Resource Icon:** Visual indicator of the resource type (e.g., storage account, virtual machine, function app).
2. **Resource Name:** The <mark style="color:$primary;">Terraform</mark> resource name you've assigned.
3. **Resource Type:** The <mark style="color:$primary;">Terraform</mark> resource type (e.g., `azurerm_storage_account`, `aws_s3_bucket`)
4. **Key Parameters:** Most important configuration values:
   * Required parameters.
   * Connection references to other resources.
   * Location/region information.
   * Names and identifiers.
5. **File Assignment:** Shows which <mark style="color:$primary;">Terraform</mark> file contains this resource.

***

## Parameter Display

Parameters are displayed in different formats based on their type:

* **Simple Values:** Strings and numbers shown directly (e.g., `"Standard"`, `"LRS"`)
* **References:** Links to other resources shown with an icon and resource name (e.g., `→ resource_group.name`)
* **Variables:** Variable references shown with variable icon (e.g., `var.location`).
* **Complex Objects:** Nested configuration indicated with a message: "View full configuration in the Resource Configurator".

{% hint style="info" %}
Parameter references are clickable - click any reference to navigate to the referenced `resource`, `variable`, or `output`.
{% endhint %}

#### **Viewing parameters**

Hover over any parameter value to see:

* Parameter documentation.
* Data type information.
* Default values.
* Validation requirements.

***

## Resource Relationship Indicators

Resource cards show relationship indicators:

* **Incoming References:** Icon shows when other resources reference this one.
* **Outgoing References:** Displayed as clickable parameter values.
* **Module Connections:** Special indicator for module-sourced resources.

***

## Card Actions

Each resource card provides quick actions:

* **Click Resource Card:** It highlights the corresponding resource in the architecture diagram. IT is useful for large diagrams where resources may be off-screen.
* **Double-Click:** Double-clicking a resource card opens the [Resource Configuration](/cloud-design/right-panel/resource-configuration) panel for detailed editing. Or, you can also right-click on the resource card and select **"Edit Config"** from the actions menu.
* **Minimize/Expand:** Toggle between collapsed and expanded parameter view.
* **Actions Menu** (⋯): Access additional options:
  * Configure resource
  * Switch to data source/resource
  * Terraform state (import resource)
  * Duplicate
  * Delete


# Resource Organization

## File Assignment

Resources are assigned to <mark style="color:$primary;">**Terraform**</mark> files based on:

* **Default Assignment:** New resources go to <mark style="color:$primary;">**`main.tf`**</mark> by default.
* **Automatic Separation:** Variables go to <mark style="color:$primary;">**`variables.tf`**</mark>, outputs to <mark style="color:$primary;">**`outputs.tf`**</mark>, etc.
* **Manual Assignment:** You can assign resources to different files. To do so:
  * Right-click the resource in the diagram.
  * Select **"Move to file"**.
  * Choose an existing file or create a new one.

Learn more in [Split Code into Files](/cloud-design/autogenerated-code/split-code-into-files).


# Best Practices and Sortcuts

## Best Practices

### Navigation

* **Use the search** for architectures with more than 10 resources.
* **Use File-Grouped View** when working with organized, multi-file architectures.
* **Click references** to quickly navigate between related resources.

### Resource Management

* **Review parameters regularly** to ensure configurations are correct.
* **Check for unset required parameters** (indicated with warning icons).
* **Use the minimize feature** to focus on specific resources while keeping others visible.

### Performance

For very large architectures (100+ resources), the interface automatically optimizes by:

* Switching to **File-Grouped** View.
* Virtualizing the card list (only rendering visible cards).
* Limiting expanded parameter displays.

***

## Keyboard Shortcuts

* <mark style="color:$primary;">`SHIFT+CMD+R`</mark> / <mark style="color:$primary;">`SHIFT+CTRL+R`</mark> : Toggle between the **`Resources`** and **`Code`** tabs.
* <mark style="color:$primary;">`CMD+F`</mark> / <mark style="color:$primary;">`CTRL+F`</mark> : Focus search input (when **`Resources`** tab is active).
* <mark style="color:$primary;">`Escape`</mark> : Clears search.
* <mark style="color:$primary;">`Enter`</mark> : When hovering a card, opens **Resource Configuration.**


# Resource Configuration

The **Resource Configuration** panel is the primary interface for configuring individual cloud resources. It provides a comprehensive form-based editor, code view, and state inspection for deep resource configuration.&#x20;

<figure><img src="/files/EZz8W0qw8niWvL0e5v1J" alt=""><figcaption></figcaption></figure>

## Overview

The **Resource Configuration** panel opens when you double-click a resource card in the [Resources List](/cloud-design/right-panel/resources-list) or double-click a resource in the diagram. It provides three views for working with resources:

1. **Form** - Structured configuration form with sections and fields (primary editing interface).
2. **State** - Read-only view of **Terraform** state attributes.
3. **Code** - Direct HCL code editor for the resource.

{% embed url="<https://cdn.brainboard.co/product_videos/guides/configurators/step-4-resource-configurator.webm>" %}
Opening and using the Resource Configuration panel
{% endembed %}

## Opening the Resource Configuration Panel

To open the **Resource Configuration** panel:

1. **From Resources List**: Navigate to the **Resources** tab in the [Right Panel](/cloud-design/right-panel) and **double-click** any resource card.
2. **From Diagram**: **Double-click** any resource node in the design area.
3. **From Node Options**: Click a resource and select **"Cloud configuration"** from the node's options bar.

{% hint style="info" %}
You can also open the **Resource Configuration** panel by selecting a resource in the diagram and pressing <mark style="color:$primary;">**`Enter`**</mark> or selecting <mark style="color:$primary;">**"Edit Config"**</mark> from the **context menu**.
{% endhint %}

## Form View

The **Form** view provides a structured interface for configuring resource parameters, organized into collapsible sections. This is the **primary and recommended way** to configure your cloud resources.

{% embed url="<https://cdn.brainboard.co/product_videos/guides/configurators/step-1-dynamic-view.webm>" %}
Dynamic form view with collapsible sections
{% endembed %}

### Form Components

#### Header

The header displays:

* **Back button** - Returns to the Resources List.
* **Resource icon and name** - Visual identifier for the current resource.
  * You can change the resource title, reset, or delete it if needed.
  * You can customize the icon.
* **Tab selector** - Switch between <mark style="color:$primary;">**Form, State**</mark>, and <mark style="color:$primary;">**Code**</mark> views.

#### Configuration Sections

The form is organized into sections:

1. **Graphics** - Resource appearance settings:
   * Icon customization
   * Resource label (displayed name in the diagram)
2. **Metadata** - Terraform-specific settings:
   * **Resource name** (Terraform identifier) - Used to uniquely identify the resource in the design and code
   * **File name** - Which `.tf` file contains this resource
   * **Provider alias** - If using multiple provider configurations
   * **Region/location settings** - For providers like AWS where location is not part of the Terraform resource
3. **Required Parameters** - Core mandatory attributes:
   * These parameters come from what **Terraform** considers required
   * Missing required fields are highlighted in red
4. **Advanced Configuration** - Optional sections and nested configurations:
   * Contains all fields that are not mandatory
   * Can be added/removed using the Sections Builder
5. **Extra Attributes** - Terraform meta-arguments:
   * `count` - Create multiple instances with a single configuration
   * `depends_on` - Specify dependencies between resources
   * `for_each` - Create multiple instances based on a map or set
   * `lifecycle` - Define actions during create, update, or delete
   * `terraform code` - Write any valid Terraform code (like provisioners)
6. **Exported Attributes** - Read-only information:
   * Attributes available to be used by other resources
   * Used in output blocks
   * Automatically filled after deployment from the tfstate file

{% hint style="info" %}
**Special Parameters:**

1. **Resource name:** The Terraform resource name. Changing this will destroy and recreate the resource. This field doesn't accept variables - use string text. Brainboard manages this field for you in most cases.
2. **Location:** For some providers like AWS, Brainboard uses this field to generate Terraform code accurately when location isn't part of the Terraform resource.
   {% endhint %}

### Section Management

Each section can be:

* **Expanded/Collapsed** - Click the section header to toggle
* **Added/Removed** - Use the Sections Builder to customize visible sections
* **Configured** - Fill in parameters specific to your infrastructure needs

#### Sections Builder

The **Sections Builder** allows you to customize which configuration blocks appear in your form.&#x20;

To use the **Sections Builder**:

1. Click the **builder icon** (grid icon) in the configurator header.
2. Browse available sections and blocks for your resource type.
3. Check/uncheck sections to add or remove them from the form.
4. The form updates immediately with your selections.

{% embed url="<https://cdn.brainboard.co/product_videos/guides/configurators/step-5-resource-builder.webm>" %}
Using the Sections Builder to add/remove configuration blocks
{% endembed %}

### Field Types

The Resource Configuration panel supports various field types that map to Terraform attributes:

#### Text Attributes

Used when the expected value is a `string` such as name, IP address, or location:

* All Terraform supported types including [string & template strings](https://developer.hashicorp.com/terraform/language/expressions/strings) and [heredoc](https://en.wikipedia.org/wiki/Here_document)
* Press Enter to switch into multiline mode for proper formatting
* No need to quote values - Brainboard handles quoting based on Terraform requirements

#### Number Attributes

For specifying numerical values (integers and floating-point numbers):

* Supports decimal or scientific notation
* Common uses: resource counts, networking parameters, timeouts
* Terraform provides [built-in functions](https://developer.hashicorp.com/terraform/language/functions) for manipulating numbers

#### List Attributes

For collections of values (any data type including strings, numbers, booleans, nested lists/maps):

* **Lists of resources** - Related resources like virtual network subnets
* **Lists of strings** - IP addresses, names, etc.
* **Lists of maps** - Sets of key-value pairs
* Can switch to text field mode to use Terraform functions (e.g., `merge` function for tags)

{% hint style="info" %}
Lists can be accessed and manipulated using [built-in functions](https://developer.hashicorp.com/terraform/language/functions) like indexing, length, concatenation, and filtering.
{% endhint %}

#### Boolean Attributes

Three options for boolean type attributes:

* **Default** - Value removed from generated code, uses Terraform default
* **False** - Explicitly set to false
* **True** - Explicitly set to true
* **Var mode** - Use expression evaluation for dynamic values

#### Block Attributes

Nested configuration blocks that can contain:

* All the field types mentioned above
* Other nested blocks
* Reset button to remove the entire block from generated code
* Add button to create multiple blocks (when supported by Terraform)

{% embed url="<https://cdn.brainboard.co/product_videos/guides/configurators/step-6-section-block-builder.webm>" %}
Using the Block Builder to configure nested blocks
{% endembed %}

{% hint style="info" %} <mark style="color:$primary;">**Brainboard**</mark> shows the option to create another block only when multiple blocks are supported in Terraform.
{% endhint %}

### Field Documentation

Each field includes inline documentation:

* **Hover over the field label** to see a tooltip with:
  * Parameter description
  * Data type
  * Default values
  * Validation rules
  * Required/optional status
* **Click the documentation icon** (?) to open the official Terraform provider documentation

### Auto-save Behavior

The form auto-saves changes:

* **On blur** - When you click outside a field
* **On mouse leave** - When your cursor leaves the form area
* **Debounced** - Changes are batched to avoid excessive saves

{% hint style="info" %}
A subtle indicator shows when changes are being saved. You don't need to manually save the form.
{% endhint %}

### Top Bar Options

Options in the top bar allow you to:

* Move the panel wherever you want in the design area
* See automatic save indicator
* Reset the changes you made
* Open the Terraform documentation of the resource
* Show/hide the documentation of every field within Brainboard
* Close the panel

### Warnings and Validation

The form displays warnings for:

* **Destructive changes** - Operations that will destroy and recreate the resource
* **Required parameters** - Missing required fields highlighted in red
* **Invalid values** - Validation errors with helpful messages
* **Type mismatches** - Incorrect data types for fields

### Extra Attributes Details

#### Count

Allows you to create multiple instances of the same resource with a single configuration:

* Use a number, variable, Terraform functions, or any valid Terraform syntax
* When a resource has count, its icon changes visually in the diagram

#### Depends\_On

Specify dependencies between resources:

* Ensures one resource is created before another
* Brainboard automatically creates a visual link between both resources

#### For\_Each

Create multiple instances based on a map or set of values:

* Can write your map directly or use a variable (best practice)
* When a resource has for\_each, its icon changes visually in the diagram

#### Lifecycle

Define actions during resource lifecycle:

* **create\_before\_destroy** - Create new resource before destroying existing one
* **prevent\_destroy** - Prevent Terraform from destroying a resource (useful for databases)
* **ignore\_changes** - Specify attributes that shouldn't trigger an update

#### Terraform Code

For advanced users, write any valid Terraform code:

* Useful for provisioners
* Custom logic not available in standard fields

## Search Feature

The Resource Configuration panel includes a powerful search feature for finding and adding parameters:

1. Click the **search icon** in the configurator toolbar
2. Type to search for:
   * Attribute names
   * Block names
   * Documentation keywords
3. Search results show:
   * **Configured attributes** - Already in your form (navigate to them)
   * **Available attributes** - Not yet added (click to add to form)

{% hint style="info" %}
Use search when you know the name of a parameter but can't find it in the sections. The search will add it to your form automatically.
{% endhint %}

## State View

The State view displays read-only Terraform state information for the resource.

### State Information

State view shows:

* **Exported Attributes** - Values generated after resource creation
* **Computed Values** - Calculated by Terraform
* **Resource IDs** - Cloud provider identifiers
* **Output Values** - Data exported for use by other resources

### When to Use State View

State view is useful for:

* **Checking resource IDs** after deployment
* **Finding computed values** to reference in other resources
* **Debugging** resource relationships
* **Understanding** what Terraform has created

{% hint style="warning" %}
State information is only available after the resource has been deployed. Newly created resources will show an empty state.
{% endhint %}

{% hint style="info" %}

1. An exported attribute is a value created by one Terraform module and made available for another module to use.
2. Once the infrastructure is deployed, Brainboard fills these fields automatically based on information from the generated tfstate file.
   {% endhint %}

## Code View

The Code view provides direct access to the Terraform HCL code for the individual resource.

<figure><img src="/files/iULrtucBY8gK5g1c0r8d" alt=""><figcaption><p>Resource Configuration code editor</p></figcaption></figure>

{% embed url="<https://cdn.brainboard.co/product_videos/guides/configurators/step-2-code-view-and-edit.webm>" %}
Viewing and editing resource code
{% endembed %}

### Code Editor Features

* **Syntax Highlighting** - Full HCL syntax support
* **Line Numbers** - Easy reference
* **Code Validation** - Real-time syntax checking
* **Keyboard Shortcuts**:
  * `CMD/CTRL+S` - Save changes
  * `CMD/CTRL+F` - Search in code
  * `CMD/CTRL+H` - Find and replace

### Bi-directional Sync

Changes in code view sync with the form view and vice versa:

* **Form → Code** - Form changes immediately update the code
* **Code → Form** - After saving code, the form updates to reflect changes

{% hint style="info" %}
The code editor operates on a single resource, making it safer than editing the full file in the main Code tab.
{% endhint %}

## Terraform Actions

The Resource Configuration panel header provides quick access to Terraform actions:

* **Validate** - Run `terraform validate` for this resource
* **Plan** - Generate an execution plan
* **Apply** - Deploy changes
* **Pull Request** - Create a PR with changes

## Special Resource Types

### Custom Resources

The Resource Configuration panel for custom resources includes additional fields:

1. You can define the Terraform resource type
2. You can indicate the source of the provider if it's in a different namespace (e.g., `cloudflare/cloudflare`)

{% hint style="info" %}
When you specify the cloud provider source, Brainboard automatically adds this entry in the provider block.
{% endhint %}

### Modules

The Resource Configuration panel for a module is built based on the variables and outputs defined in the module's source code:

1. **Refresh button** - Fetch the latest version from Git or registry and rebuild the form
2. **Source** - The module source location (change in modules' catalog)
3. **Version** - Specific version, branch, or tag
4. **Documentation** - Comes from the description of the module's variables

## Navigation and Keyboard Shortcuts

### Navigation

* **Back button** - Returns to Resources List (retains scroll position)
* **Close button** (X) - Closes configurator and returns to Resources tab
* `ESC` key - Closes the configurator

### Keyboard Shortcuts

* `CMD/CTRL+F` - Open search (when Form tab is active)
* `Enter` - (When field is focused) Move to next field
* `Tab` - Navigate between fields
* Arrow keys - Navigate section headers

## Resizer

The panel includes a resizer that allows you to:

* Adjust width by dragging the left edge
* Adjust height by dragging the bottom edge
* Resize to make it bigger or smaller based on your preference

## Best Practices

### Form Configuration

* **Start with Required Parameters** - Configure mandatory fields first
* **Use the Sections Builder** - Customize your form to show only what you need
* **Leverage Search** - Quickly find and add obscure parameters
* **Check Documentation** - Hover over fields to understand their purpose
* **Use References** - Link to other resources instead of hardcoding values

### Resource Organization

* **One resource at a time** - The configurator is designed for focused editing
* **Use references** - Link to other resources, variables, or outputs
* **Group related resources** - Keep connected resources in the same file

### Performance

* **Minimize expanded sections** - Collapse sections you're not actively editing
* **Avoid excessive nesting** - Deeply nested blocks can impact form performance
* **Use code view for bulk changes** - When adding many attributes at once

## Common Workflows

### Adding a New Block

1. Click the **Sections Builder** icon
2. Find the block you want to add (e.g., "logging")
3. Check the checkbox to add it to your form
4. Configure the block parameters

### Referencing Another Resource

1. Click the field that needs a reference
2. Select **Reference** from the dropdown (if applicable)
3. Choose the resource, variable, or output to reference
4. The form automatically creates the correct Terraform reference syntax

### Creating Dependencies

1. In the **Extra Attributes** section, find `depends_on`
2. Select the resource(s) this resource depends on
3. Brainboard automatically creates a visual link in the diagram

### Using Count or For\_Each

1. In the **Extra Attributes** section, find `count` or `for_each`
2. Enter your expression:
   * **Count**: A number, variable, or expression
   * **For\_each**: A map or set (best practice: use a variable)
3. The resource icon changes visually to indicate multiple instances

### Viewing Computed Values

1. Deploy your architecture
2. Open the resource in the Resource Configuration panel
3. Switch to the **State** tab
4. Find the computed value you need
5. Copy it or reference it in other resources

## Troubleshooting

### Form Not Saving

If changes aren't saving:

* Check for validation errors (red highlights)
* Ensure required fields are filled
* Try clicking outside the field to trigger save
* Check the browser console for errors

### Missing Sections

If expected sections don't appear:

* Check the **Sections Builder** - they may be hidden
* Verify the resource type supports the block
* Check if using a module (module resources have limited configuration)

### Code and Form Mismatch

If code and form show different values:

* Save the code explicitly with `CMD/CTRL+S`
* Refresh the form by closing and reopening the configurator
* Check for syntax errors in the code

## See Also

* [Resources List](/cloud-design/right-panel/resources-list) - Resource list and overview
* [Right Panel](/cloud-design/right-panel) - Overview of right panel features
* [Code Edition](/cloud-design/code-edition) - Full file code editing
* [Design Area](/cloud-design/design-area) - Visual diagram interface
* [Terraform Actions](/cloud-design/autogenerated-code/terraform-opentofu-actions) - Running Terraform commands
* [Node](/cloud-design/design-area/node) - Working with resource nodes in the diagram


# One action

### Description

At the top of the right panel, the expandable tab containing the Terraform action buttons is termed the <mark style="color:$primary;">**One-action**</mark> tab.

<mark style="color:$primary;">**One action**</mark> is a quick way to execute a Terraform action without triggering the pipeline.

### Terraform Actions

1. **Validate:** This executes <mark style="color:$primary;">**`terraform validate`**</mark> on the generated code and gives you the output.
2. **Plan:** It performs <mark style="color:$primary;">**`terraform plan`**</mark> on the generated code and gives you the output.
3. **Apply:** It runs <mark style="color:$primary;">**`terraform apply -auto-approve`**</mark> on the generated code and gives you the output.
4. **Destroy:** It performs <mark style="color:$primary;">**`terraform destroy -auto-approve`**</mark> on the generated code and gives you the output.

{% hint style="info" %}
Before doing any action, Brainboard sets this up: <mark style="color:green;">**`terraform init -input=false -upgrade=true`**</mark>

This is to make sure everything is set up correctly before launching the execution of the action.
{% endhint %}

<figure><img src="/files/wNZLNiQTiF1Cpx7xYVne" alt=""><figcaption></figcaption></figure>

{% hint style="success" icon="lightbulb" %}
This is useful when building infrastructure to quickly launch a plan or run validation checks to ensure the code is valid and preview the changes that will be introduced. That’s why it is located next to your design.
{% endhint %}

### How it works

When you trigger an action in <mark style="color:$primary;">**`one-action`**</mark> tab, Brainboard:

* creates an ephemeral execution environment,
* executes the action, and
* streamlines the output in real time.

{% hint style="info" icon="clock" %}
**Time stamp:** You can also find the timestamp in the bottom-right corner. It is displayed in the UTC timezone to indicate when the action was performed.
{% endhint %}

This execution will also be logged in the pipeline history, so you can visualize it at any time. It is named <mark style="color:$primary;">**“One Action pipeline”**</mark> in the workflow column.

<figure><img src="/files/eaJHnKZgiaVzrlx4U1M5" alt=""><figcaption></figcaption></figure>

### Stop the execution

When there is an ongoing execution, you can stop it by clicking on the <mark style="color:red;">**`Stop`**</mark> button located in the top-right corner of the output.

<figure><img src="/files/eb3lJoR6f6XdiBuDVAvX" alt=""><figcaption></figcaption></figure>

{% hint style="warning" icon="lightbulb" %}
You can also stop the execution from the pipeline view
{% endhint %}

<figure><img src="/files/eaJHnKZgiaVzrlx4U1M5" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
When you stop an ongoing <mark style="color:$primary;">**`apply`**</mark> or <mark style="color:$primary;">**`destroy`**</mark>, Brainboard attempts to gracefully shutdown the execution process, but in some rare cases, the **Terraform state** may get **corrupted.** If you encounter this situation, reach out to our support by clicking the **Help** icon in the top right corner of your Brainboard dashboard.
{% endhint %}

### Targeting

Brainboard allows you to execute an action on a specific resource. For example, you want to destroy a specific resource(s) on an already deployed architecture without impacting the whole infrastructure.

To achieve this, type the resource address in the menu or select it from the dropdown menu, then click any action.

{% hint style="info" %}
Refer to [this documentation page](https://developer.hashicorp.com/terraform/cli/commands/plan#resource-targeting) to understand how resource targeting works in Terraform.
{% endhint %}

### Output

Brainboard provides real-time output of the current execution.

When you first open the <mark style="color:$primary;">**one-action**</mark> tab, Brainboard displays the output of the last execution.

This output is shared for all users who have access to the architecture, as it is important to know what happened during the last execution when you are about to make new changes.

### Best practices

When you are building a cloud architecture, it's advised to do <mark style="color:$primary;">**`plan`**</mark> frequently to catch errors at an early stage and fix them.


# Code Panel

{% hint style="warning" icon="circle-info" %}
**ALPHA FEATURE NOTICE**

Code Edition is currently an Alpha feature. This means it's under development. We encourage [feedback](/help-and-faq/support) to help us improve it!
{% endhint %}

## Code Panel: Directly Edit Your Terraform Code

Brainboard's **Code Edition** feature allows you to directly view and modify the auto-generated Terraform HCL code for your cloud infrastructure designs. While Brainboard promotes a "**design-first**" approach where configurations are primarily managed through the visual interface and [Resource Configuration](/cloud-design/right-panel/resource-configuration) panel, **Code Edition** provides flexibility for users who are comfortable with or prefer direct code manipulation for specific tasks.

<figure><img src="/files/FjRAIj98HnlBEWWpK2Db" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/b7sxDDDY2XqYZmXS4wh0" alt=""><figcaption><p>Code panel banner</p></figcaption></figure>

## Why Use Code Edition?

* **Flexibility:** Make specific changes or additions to your **Terraform** code that might be quicker or more intuitive for code-centric users.
* **Familiar Environment:** For users accustomed to writing **Terraform,** this offers a direct way to interact with the configuration.
* **Quick Fixes:** To rapidly address minor issues or apply specific configurations directly in the code.
* **Pasting Existing Code:** Incorporate snippets of **Terraform** code from documentation or other sources (with some considerations, see "**Pasting New Resources**" below).

## Accessing and Using Code Panel

The **Code** panel is always visible on the right-hand side of the Brainboard design canvas.

### **Select a File**

At the top of the **Code** panel, you'll find a file selector. You can choose from standard **Terraform** files like:

* <mark style="color:$primary;">**`main.tf`**</mark>
* <mark style="color:$primary;">**`variables.tf`**</mark>
* <mark style="color:$primary;">**`locals.tf`**</mark>
* <mark style="color:$primary;">**`outputs.tf`**</mark>

{% hint style="warning" %}
Note: **`providers.tf`** and **`backend.tf`** are not yet editable through this feature to maintain Brainboard's core functionality.
{% endhint %}

<figure><img src="/files/Z5RycIdRk9HRmTG36xVE" alt=""><figcaption></figcaption></figure>

### **View Code**

The content of the selected file will be displayed in the editor.

### **Edit Code**

Simply click into the code editor and begin making your changes.

{% hint style="info" %}
The editor is based on **Monaco Editor** (the same editor that powers **VS Code**) and provides:

* Syntax highlighting for **Terraform HCL.**
* Search (**`CMD/CTRL+F`**).
* Find and Replace (**`CMD/CTRL+H`**).

*👉🏻 Future enhancements may include suggestions, linting, and more advanced features.*
{% endhint %}

### **Saving Changes**

1. To save your changes, press <mark style="color:$primary;">**`CMD+S`**</mark> (on macOS) or <mark style="color:$primary;">**`CTRL+S`**</mark> (on Windows/Linux).
2. Upon saving, **Brainboard** will:
   1. <mark style="color:$primary;">**Parse**</mark> the modified code.
   2. <mark style="color:$primary;">**Validate**</mark> the **HCL** and **Terraform** syntax. <mark style="color:red;">**Errors**</mark> will be displayed if issues are found.
   3. <mark style="color:$primary;">**Transform**</mark> the changes into Brainboard's internal format.
   4. <mark style="color:$primary;">**Update**</mark> the visual diagram if your code changes imply structural modifications (e.g., adding new resources, creating connections).
   5. And finally, re-generate the relevant Terraform files.

{% hint style="warning" icon="note-sticky" %}
New resources added via code will typically be appended to the diagram and may need to be manually repositioned.
{% endhint %}

#### **Discarding Unsaved Changes**

To discard any unsaved modifications you've made directly in the editor without saving, you can use the shortcut <mark style="color:$primary;">**`CMD+SHIFT+R`**</mark> (macOS) or <mark style="color:$primary;">**`CTRL+SHIFT+R`**</mark> (Windows/Linux).

#### **Unsaved Changes on Navigation**

If you attempt to leave the page or navigate away with unsaved changes in the code editor, you will be prompted to either <mark style="color:$primary;">**`Continue editing`**</mark>**,** <mark style="color:red;">**`Discard changes`**</mark>**,** or <mark style="color:$primary;">**`Save changes`**</mark>**.**

<figure><img src="/files/3nXAqw1uA9RsoXSCF2Yr" alt=""><figcaption></figcaption></figure>

## How Code Interacts with the Visual Diagram

Brainboard aims for a synchronized experience between the visual design and the code:

{% hint style="info" icon="code" %}

### **Diagram/Resource Configuration to Code**

Any modifications made to your infrastructure through the visual diagram (dragging, moving resources) or by configuring resources via the [Resource Configuration](/cloud-design/right-panel/resource-configuration) panel will automatically trigger **re-generation** of the relevant **Terraform code**, which you will see updated in the **Code** panel.\\
{% endhint %}

{% hint style="info" icon="diagram-project" %}

### **Code to Diagram**

Changes saved in the Code Editor that define new resources or modify existing ones in a way that impacts the diagram's structure (e.g., adding a `resource` block) will be reflected visually. New resources are typically appended to the diagram and may require manual placement.
{% endhint %}

## Key Features and Behaviours

### **1. Syntax Highlighting**

Makes reading and editing **Terraform HCL** easier.

### **2. Code Validation**

On save, Brainboard validates the **HCL** syntax and basic **Terraform** structure. Errors will be reported to help you fix them.

<figure><img src="/files/VXSnRZvinWBCHYtCDnd0" alt=""><figcaption></figcaption></figure>

### **3. File Management**

You can view and edit code within predefined files (<mark style="color:$primary;">**`main.tf`**</mark>, <mark style="color:$primary;">**`variables.tf`**</mark>**,&#x20;**<mark style="color:$primary;">**`terraform.tfvars`**</mark>**,&#x20;**<mark style="color:$primary;">**`locals.tf`**</mark>**).**

### **4. Moving Resources to Different Files**

While you cannot create new files directly from the **Code** panel *yet*, you can reassign a resource to a different file (or create a new logical file group for it) by **right-clicking the resource** in the diagram and selecting ["Edit TF filename."](/cloud-design/autogenerated-code/split-code-into-files)

After reassigning, you can then edit the resource's code within its newly designated file in the **Code** panel.

### **5. Warnings for Misplaced Blocks**

Brainboard expects certain definitions to reside in specific files. For example, <mark style="color:$primary;">**`variable`**</mark> blocks should be in <mark style="color:$primary;">**`variables.tf`**</mark> and <mark style="color:$primary;">**`locals`**</mark> blocks in <mark style="color:$primary;">**`locals.tf`**</mark>.

{% hint style="warning" %}
If you define a <mark style="color:$primary;">**`variable`**</mark> block in <mark style="color:$primary;">**`main.tf`**</mark>, upon saving, Brainboard automatically move the defined variable to the appropriate file (e.g., <mark style="color:$primary;">**`variables.tf`**</mark>).
{% endhint %}

<figure><img src="/files/DbFpgaehEYvqKouPcGhA" alt=""><figcaption></figcaption></figure>

### Important Limitations (ALPHA)

As **Code** is an *<mark style="color:$primary;">**Alpha**</mark>* feature and **Brainboard** primarily manages infrastructure through its structured visual paradigm, there are some important limitations to be aware of:

1. **Resource Renaming:** You cannot rename a resource (e.g., changing <mark style="color:$primary;">**`resource`**</mark> <mark style="color:orange;">**`"azurerm_virtual_network""vnet-aksc"`**</mark> to <mark style="color:$primary;">**`resource`**</mark> <mark style="color:orange;">**`"azurerm_virtual_network""my_new_vnet"`**</mark>) directly in the **Code** panel yet. The resource name is a critical part of its identifier within Brainboard.

{% hint style="info" icon="pen-field" %}
**How to Rename**

To rename a resource, please use the **Resource Configuration** panel. Brainboard will then automatically propagate this name change throughout your configuration, updating all references to ensure consistency.
{% endhint %}

<figure><img src="/files/qk912vT3Z7Lvdrex71sk" alt=""><figcaption></figcaption></figure>

2. **Supported Feature Only:** Only **Terraform** configurations and structures that are supported by Brainboard's GUI (the visual designer and <mark style="color:$primary;">**Resource Configuration**</mark> panel) are guaranteed to be preserved.
3. **No Comment Preservation:** Comments in the code are currently <mark style="color:red;">**not saved**</mark> or preserved. When Brainboard parses and re-generates the code, comments will be stripped out.
4. **No Attribute or Block Order Preservation:** The order of attributes within a resource block or the order of blocks within a file may not be preserved. Brainboard will re-generate the code based on its own ordering rules.
5. **Restricted File Edits:** Certain files are crucial for Brainboard's operation, such as <mark style="color:$primary;">**`providers.tf`**</mark> or <mark style="color:$primary;">**`backend.tf`**</mark>, and are generally not editable, or changes might be overwritten.
6. **Pasting New Resources:** When pasting a new resource block from external documentation:
   1. The resource will be created.
   2. It will be appended to the right side of your diagram and will likely need to be manually moved to the desired position.

### Customizing the Editor

You can customize some aspects of the <mark style="color:$primary;">**Monaco**</mark> editor's appearance and behaviour:

1. Ensure the design canvas (diagram area) has focus (click on an empty space in the diagram).
2. Press <mark style="color:$primary;">**`CMD+K`**</mark> (macOS) or <mark style="color:$primary;">**`CTRL+K`**</mark> (Windows/Linux).
3. In the <mark style="color:$primary;">**command palette**</mark> that appears, search for and select <mark style="color:$primary;">**`update editor settings.`**</mark>
4. An <mark style="color:$primary;">**`Editor configuration`**</mark> dialogue will appear, allowing you to change settings like <mark style="color:blue;">**`fontSize`**</mark>, **`fontWeight`**, <mark style="color:blue;">**`lineNumbers`**</mark>, <mark style="color:blue;">**`tabSize`**</mark>, etc., in a **JSON** format.
5. Click "Confirm" to apply your changes or "Reset to default" to revert.

<figure><img src="/files/wbvqIo4ltOd0lscUGR50" alt=""><figcaption><p><em><strong>The command palette modal/dropdown that appears after pressing CMD/CTRL+K, with "update editor settings" typed in the search bar and the option highlighted.</strong></em></p></figcaption></figure>

### Best Practices

{% hint style="success" icon="file-arrow-down" %}
**Save Frequently**

Use <mark style="color:$primary;">**`CMD/CTRL+S`**</mark> regularly to save your changes and ensure they are parsed and validated by Brainboard. Also, remember <mark style="color:$primary;">**`CMD/CTRL+SHIFT+R`**</mark> if you need to quickly discard unsaved changes in the editor.
{% endhint %}

{% hint style="success" icon="code" %}
**Prioritize Visual Design for Structure**

For major structural changes, adding new resources, or defining relationships, it's often best to use the visual designer and **Resource Configuration** panel. Use the **Code** panel for fine-tuning or specific code-level adjustments.
{% endhint %}

{% hint style="success" icon="comment-lines" %}
**Understand the Re-generation Process**

Be aware that Brainboard parses your code changes and then re-generates the files. This is why comments and exact formatting may not be preserved.
{% endhint %}

{% hint style="success" icon="magnifying-glass-arrows-rotate" %}
**Check Diagram After Code Changes**

If you add or significantly modify resources via code, always **review** the visual diagram to ensure the changes are reflected as expected and adjust placement if necessary.
{% endhint %}


# Autogenerated code


# What & how code is generated


# Split code into files


# Terraform / OpenTofu actions


# Download code


# Pull requests


# Data structure


# Project

### Definition

{% hint style="info" %}
A **project** is a container of environments and architectures to which teams have access with specific permissions.
{% endhint %}

💡Think of a project as an upper level folder.

{% hint style="info" %}
By default, members don't have direct permissions on projects unless the admin grants them access to.
{% endhint %}

***

### Create a new project

To create a new project:

1. Go to the [projects setting page](https://app.brainboard.co/settings/projects).
2. Click on the <mark style="color:$primary;">**`Create project`**</mark> button.

<figure><img src="/files/e5lgJN3EGJ0XAzwA0vzi" alt=""><figcaption></figcaption></figure>

3. You will then go through a **project creation wizard** comprising of three steps:

* **First step:** Here, you will set up the **name, description and environments** of the new project.

{% hint style="info" %}
Brainboard creates 5 environments by default: **Production, Staging, Development, Test** and **QA.**

You can also add any custom environment as well
{% endhint %}

{% hint style="warning" %}
The **project name** and at least one **environment** are required to create a new project.
{% endhint %}

<figure><img src="/files/9IFsPbQ1qmGo8eQ6tXjA" alt=""><figcaption></figcaption></figure>

* **Second step:** Here, you will need to assign **teams** to **roles**. You can do that by dragging and dropping each team into the corresponding role.

{% hint style="warning" %}
You need to assign at least one team with the *admin* role.
{% endhint %}

<figure><img src="/files/34AzLH6bj3ctRGEi2v3o" alt=""><figcaption></figcaption></figure>

* **Third step:** Here, you can view the summary of the new project: *<mark style="color:$primary;">name, description, environment</mark>* and the *<mark style="color:$primary;">teams</mark>* assigned to this project with their *<mark style="color:$primary;">roles</mark>*.

4. Click the <mark style="color:$primary;">**`Create project`**</mark> button to save your project details.

<figure><img src="/files/axTG9k3VrLPbjZFAQisW" alt=""><figcaption></figcaption></figure>

Upon clicking the <mark style="color:$primary;">**`Create project`**</mark> button, the new project's details will be saved, and you will be navigated to the[ project settings page](https://app.brainboard.co/settings/projects), where you can view the project details as well as edit it.

### View the project's information

To view the information on a specific project:

1. Go to the [projects setting page](https://app.brainboard.co/settings/projects).
2. Click on the <mark style="color:$primary;">**`+`**</mark> icon next to the project name, and the project's details will be expanded, such as:

* Name of the project.
* Teams that have access to this project with their respective roles.
* The environments of the project.

<figure><img src="/files/lk6wMnldQnGhTiEuXHu2" alt=""><figcaption></figcaption></figure>

Alternatively, you can click on the <mark style="color:$primary;">**`ellipsis icon`**</mark> next to the project name, and then select the <mark style="color:$primary;">**`View details`**</mark> option from the dropdown menu.

<figure><img src="/files/dH9iIcxnrqjQZH7WI5j1" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Click the **cross&#x20;**<mark style="color:$primary;">**`x`**</mark> icon to collapse the project details view.
{% endhint %}

### Edit project information

To edit the information on a project:

1. Go to the [projects setting page](https://app.brainboard.co/settings/projects).
2. Click on the <mark style="color:$primary;">**`ellipsis icon`**</mark> next to the project name, and then select the <mark style="color:$primary;">**`Edit project details`**</mark> option from the dropdown menu.

<figure><img src="/files/437hLmnoUbBongzIirxO" alt=""><figcaption></figcaption></figure>

3. You can alter the project *<mark style="color:$primary;">name, description</mark>,* and *<mark style="color:$primary;">environments.</mark>*
4. Click on the <mark style="color:$primary;">**`Save changes`**</mark> button in the top right corner of the <mark style="color:$primary;">**Edit project details**</mark> slide-out panel to save the new information.

<figure><img src="/files/ljxRhN0O1dosRuefKn7p" alt=""><figcaption></figcaption></figure>

### Edit project roles

{% hint style="info" %}
By default, the following four types of roles are available for a <mark style="color:$primary;">**Brainboard**</mark> project:

* Admin
* Designer
* Operator
* Guest
  {% endhint %}

To assign a role to a team:

1. Go to the [projects setting page](https://app.brainboard.co/settings/projects).
2. Click on the <mark style="color:$primary;">**`ellipsis icon`**</mark> next to the project name, and then select the <mark style="color:$primary;">**`Assign teams`**</mark> option from the dropdown menu.

<figure><img src="/files/ioXzJsIrJku5WqdzR373" alt=""><figcaption></figcaption></figure>

3. You can assign a role to a team as you did when you created a new project - simple **drag and drop a team** to the specific **role** that you want to assign to it.
4. Click on the <mark style="color:$primary;">**`Update`**</mark> button to save the new information about the project.

{% hint style="warning" %}
Only the roles that are predefined for **Projects** on the [Roles page](https://app.brainboard.co/settings/roles) will be available for assignment.

For details, read the [Project Roles and Permissions](/data/data-structure/project-roles-and-permissions) article.
{% endhint %}

### Delete project

To delete a project:

1. Go to the [projects setting page](https://app.brainboard.co/settings/projects).
2. Click on the <mark style="color:$primary;">**`ellipsis icon`**</mark> next to the project name, and then select the <mark style="color:$primary;">**`Delete project`**</mark> option from the dropdown menu.
3. You'll be asked to confirm the deletion. To do so, type the word "<mark style="color:$primary;">**DELETE**</mark>" in the input field, and click the <mark style="color:$primary;">**`Yes, delete project button`**</mark>.

{% hint style="warning" %}
Once you confirm the deletion action, the project will be permanently deleted.
{% endhint %}

{% hint style="info" %}
If there is only one project in your account, it cannot be deleted since your account needs at least one project.
{% endhint %}

<figure><img src="/files/Edy4P4znzdIYA1AZFXOY" alt=""><figcaption></figcaption></figure>


# Project Roles and Permissions

## Project roles

Granting access to a team or members gives them access to the environments and architectures hosted inside the project.

Different roles can be granted to teams for the project, and you can create custom roles with custom permissions, but **Brainboard** comes with 4 default roles out of the box:

#### 1. Admin

The members of a team having the <mark style="color:$primary;">**admin**</mark> role can perform any action on the project, its environments, architectures, versions, and deployments.

#### 2. Designer

The members of a team having the <mark style="color:$primary;">**designer**</mark> role can perform any action as the admin team, except for modifying the project information or deleting it.

#### 3. Operator

The members of a team having the <mark style="color:$primary;">**operator**</mark> role can manage the deployments only; they cannot change the design of the infrastructure.

#### 4. Guest

The members of a <mark style="color:$primary;">**guest**</mark> team can only view the project, its architectures, and deployments. They cannot change anything.

## Permissions

To check the permissions a specific team has on a project:

1. Go to the [Roles page](https://app.brainboard.co/settings/roles).
2. Switch to the <mark style="color:$primary;">**Project**</mark> tab.
3. Click on the role name.

<figure><img src="/files/UtgW0PQPw0qvjVG1Ae0F" alt=""><figcaption></figcaption></figure>

This will display the permissions table:

<figure><img src="/files/q6o736eM2JWjfafZOpoJ" alt=""><figcaption></figcaption></figure>

### Assign/Unassign Permissions

To edit the permissions of a specific role, simply follow these steps:

1. Click on the <mark style="color:$primary;">**pencil (edit)**</mark> icon given next to the role's name.

<figure><img src="/files/uWsw3LzxeRFbYVX7tOyu" alt=""><figcaption></figcaption></figure>

2. On the <mark style="color:$primary;">**Role Settings**</mark> wizard, click on the **action/function name** for which you want to give permission to the role. For example, in the image shared below, we are assigning the <mark style="color:$primary;">**`Create`**</mark> **variables** permission to the <mark style="color:$primary;">**Operator**</mark> role.

{% hint style="success" %}
Once the permission is assigned, the **action/function** button will be highlighted in dark purple.
{% endhint %}

<figure><img src="/files/fhn2GY6IGDPFYC0Rbq8h" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To unassign a permission, click the highlighted **action/function** name for which you want to remove the permission from the role. The action/function button will no longer be highlighted in dark purple.
{% endhint %}


# Environment

### Description

An <mark style="color:$primary;">**`environment`**</mark> is a logical grouping of cloud architectures that are supposed to have the same criticality or serve the same purpose. Like dev, staging, QA, prod…

Environments can be used to separate and <mark style="color:$primary;">**`isolate`**</mark> development, staging, and production resources, or to create dedicated environments for different teams or applications.

{% hint style="info" %}
Brainboard environments provide a flexible and powerful way to manage your cloud infrastructure. It is like a folder; you can put any logic that reflects your processes.
{% endhint %}

### Create a new environment

You can define or create a new environment in the following two ways:

1. While creating a new project
2. While editing a new project

{% hint style="info" %}

* Multiple new environments can be defined at a time.
  {% endhint %}

## Predefined Environments

The following environments are already predefined in <mark style="color:$primary;">**Brainboard**</mark> for you to select from when creating a new project or assigning an environment to a project in project edit mode.

* Production
* Staging
* Test
* QA
* Sandbox
* UAT

<figure><img src="/files/cW8IHlrHjuyP3vDc7dI3" alt="" width="528"><figcaption></figcaption></figure>

### Creating a new environment in the New Project Details modal

1. To define a new environment at the time of new project creation, either go to <mark style="color:$primary;">**Settings > Projects**</mark> or simply click <mark style="color:$primary;">**Projects**</mark> in the left menu.
2. Click the <mark style="color:$primary;">**`Create project`**</mark> button.
3. Type in the new environment name that you want to create in the <mark style="color:$primary;">**`Environments`**</mark> field.

<figure><img src="/files/TAMSbMe4l8DSpZ6qdyRf" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Project environments are scoped to the individual project in which they are created. As a result, an environment defined for one project cannot be shared across multiple projects.
{% endhint %}

### Creating a new environment in the Edit Project Details modal

1. To define a new environment at the time of editing a project, click <mark style="color:$primary;">**Settings**</mark> in the left menu.
2. Then click <mark style="color:$primary;">**Projects**</mark>**.**
3. Click the **ellipses icon (three dots)** next to the project you want to define a new environment for.
4. Select <mark style="color:$primary;">**Edit project details**</mark> from the dropdown list.
5. Type in the new environment name that you want to create in the <mark style="color:$primary;">**`Environments`**</mark> field.

<figure><img src="/files/Z0qU3ZRcKAbgZReXfKnf" alt=""><figcaption></figcaption></figure>

### Delete environment

To delete an environment other than the predefined environments, simply open the project in edit mode and click the **cross icon&#x20;**<mark style="color:$primary;">**`(x)`**</mark> on the **environment name** that you want to delete.

{% hint style="warning" %}
Pre-defined environments cannot be deleted.
{% endhint %}

<figure><img src="/files/F3KmWYTvBGq75M1EKzVn" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Deleting an environment will delete all architectures inside it. This action cannot be undone.

Therefore, you will be prompted with a confirmation message if there is an architecture associated with the environment you wish to delete.
{% endhint %}

### Synchronize architectures across environments

Refer to the [Architecture Synchronization](/data/data-structure/cloud-architecture/synced-architectures) to know more about it.

By following these steps, you can effectively manage multiple environments in <mark style="color:$primary;">**Brainboard**</mark> and ensure that your infrastructure is consistent and reliable across all stages. This is the best way to eliminate the drift between different environments.


# Cloud architecture

![brainboard-architecture-graphical-nodes](/files/OxeTJSPIJXZKTdKAbAFb)

### Description

Cloud architecture represents a real infrastructure that is either deployed or to be deployed.

* It is the container and the graphical face of your cloud resources.
* Architectures are located within an environment inside a project.
* In terms of Terraform, it has its own Terraform state file.
* It supports modules and private git repository natively.
* It has its own CI/CD pipelines to allow you to check its security posture, pricing, policies...before introducing any change.

### Components

Think of the architecture as a git repository containing all cloud resources of your infrastructure.

#### 1. Architecture information

All high-level information related to the architecture is accessible from the list of projects, environments and architectures.

![Architecture info](/files/l0HM5QKmD4D0lx72guha)

Here is the explanation of all fields:

* Name of the architecture.
* Status of the architecture:
  * `WIP`
  * `Reviewing`
  * `Approved`
  * `Rejected`
  * `Deployed`
  * `Destroyed`
  * `Decommissioned`
  * `Locked`
* Description of the architecture.
* Tags: list of tags.
* Created at: read-only field. The creation timestamp in UTC.
* Updated at: read-only field. The last time this architecture has been updated in UTC format.
* UUID: architecture unique identifier. This number is useful when you reach out to the support.

#### 2. Nodes

The node is a fundamental component of the architecture, it represents (in most cases) a cloud resource of a given cloud provider.

* Every node has an identity card that contains its cloud configuration.
* This identity card represents the Terraform configuration parameters of the node. e.g.
  * `azurerm_lb`
  * `aws_instace`
  * `google_app_engine_application`
* You have the possibility to connect nodes by using the connectors from any selected node.

There are **5** types of nodes:

1. Cloud resource: this resource will be created when you provision the infrastructure.
2. Data source: it refers to an existing cloud resource.
3. Module: Terraform module.
4. Container: it can contain other resource and give them its properties. E.g. AWS VPC, or Azure virtual network.
5. Icon only: this resource is just graphic and has no Terraform representation.

#### 4. Variables

These are `Terraform variables` and `locals` that you can define and use both in the design and during deployment.

Refer to the [variables](/input-output/variables) page for a detailed explanation.

#### 5. Output

This is `Terraform output` that you can define and use both in the design and during deployment.

Refer to the [output](/input-output/output) page for a detailed explanation.

#### 6. README file

You can document for your infrastructure using Markdown.

Refer to the [Readme file](/data/data-structure/cloud-architecture/readme-file) page for a detailed explanation.

#### 7. Versions

You can track every change you do to the infrastructure by creating as many versions as you want.

Refer to the [versioning](/cloud-design/design-area/versioning) page for detailed explanation.

### Operations

#### Create architecture

![Create architecture](/files/bSvMkcFdTvLzYCv9hXah)

You have different ways to create an architecture:

1. **Create blank architecture**:

   <figure><img src="/files/tE3UgkCExi6Bq4Dg8OgN" alt=""><figcaption></figcaption></figure>
2. **Clone a template from the templates' catalog**:

   <figure><img src="/files/Ka22qD0HGgQOiw8mvhCs" alt=""><figcaption></figcaption></figure>

   Refer to the [templates page](/data/data-structure/template) for more details.

3\. **Import existing architecture**:

<figure><img src="/files/Ti1l5paaPqIxRD3MVolf" alt=""><figcaption></figcaption></figure>

Choose the source of the import, then import your infrastructure:

![Import options](/files/iP6hHgt1ymIyY46rtd9n)

If you select Git as a source then you'll have the list of the supported Git providers:

![Import options](/files/x6mA6CzUq4IrnVGD6hb1)

{% hint style="info" %}
Default tags By default, when you create a new architecture, Brainboard adds a variable called `tags` that contains the UUID of the architecture and the environment name.<br>

This variables will be added in all resources that support tagging using Terraform best practice using the function `merge`. It will look like this line of code:

```hcl
tags = merge(var.tags, {})
```

{% endhint %}

#### Multi-user edition

Multiple users can connect to the same architecture and collaboratively build it.

All you have to do is to invite your colleagues and give them rights to edit the architecture.

#### Clone architecture

You can clone an architecture either within the same environment or into another one.

To clone an architecture:

1. Open the architecture selector by clicking in the name of the architecture in the top bar:

   <figure><img src="/files/MRpp4aaX7heePPpHH6yn" alt=""><figcaption></figcaption></figure>
2. Hover the line of the architecture, and click on `Clone this architecture` button:

   <figure><img src="/files/jbBBQigZF6TC6rFDEc72" alt=""><figcaption></figcaption></figure>
3. In clone menu, specify:
   * Target environment.
   * Name of the new architecture and add a description.
   * Leave the sync option disabled.
   * Click `Next` to finalize the operation.
4. If the clone is successful, you'll be switched into the new architecture.
   * If the clone fails, you'll receive an error detailing the reason of the failure.

{% hint style="info" %}

* Cloning an architecture also clones its history (versions), its variables, outputs and README file.
* When cloning an architecture, the variables are cloned but not their values.
  {% endhint %}

#### Promote architecture into another environment

Promoting an architecture into another environment is the same operation as cloning, you just have to specify a different target environment.

#### Create a template from an architecture

You have the possibility to create a template from any architecture, as follows:

1. Open the architecture selector by clicking in the name of the architecture in the top bar:

   <figure><img src="/files/MRpp4aaX7heePPpHH6yn" alt=""><figcaption></figcaption></figure>
2. Hover the line of the architecture, and click on `Create template from this architecture` button:

   <figure><img src="/files/4eUqklpaMRcfZrYKvKPc" alt=""><figcaption></figcaption></figure>
3. In clone menu, specify:
   * You are reminded to remove any sensitive information since the template will be used by others.
   * Specify the visibility of the template:
     * Organization: this means that the template will be visible only to users that are within your organization.
     * Public: the template will be visible to any Brainboard user.
   * Specify a new name and description
   * Click `Next` to publish the template into the templates' catalog.
4. If the action is successful, a new project will be created named `Template catalog` with a new environment `Templates` and the new template will be visible inside.

   <figure><img src="/files/pJrKLuZGSUxOdcxcFPB8" alt=""><figcaption></figcaption></figure>

This allows you to access, maintain or delete the template. - If the action fails, you'll receive an error detailing the reason of the failure.

{% hint style="info" %}

* You cannot delete the project `Template catalog` nor the environment `Templates`. They will be removed automatically when you remove all your templates.
* The newly created template will be available in the templates' catalog.
  {% endhint %}

#### Delete architecture

To delete an architecture:

1. Open the architecture selector by clicking in the name of the architecture in the top bar:

   <figure><img src="/files/MRpp4aaX7heePPpHH6yn" alt=""><figcaption></figcaption></figure>
2. Select the architecture(s) you want to delete.
3. Click on `Delete the selected architectures` button:

   <figure><img src="/files/yWmdBzQVl5kdoOi9ILQe" alt=""><figcaption></figcaption></figure>
4. Confirm the action to delete the architecture(s).
5. If you are authorized to delete the selected architecture(s) and the operation succeed, the architecture(s) will be removed from the listing.
   * If you are not allowed to delete the architecture(s) or the operation fails, you'll receive an error detailing the reason of the failure.

{% hint style="warning" %}
Deleting an architecture, environment or project cannot be undone
{% endhint %}

### Deploy architecture

To deploy your architecture, you have 2 options:

1. Either, use `one-action` to trigger Terraform `apply`. Refer to the [one-action](/cloud-design/one-action) documentation for more details.
2. Or, build pipelines with Brainboard CI/CD engine and trigger it. Refer to the [CI/CD engine](/automation/ci-cd-designer) documentation for detailed steps.

### Best practices

* Always build default pipeline that contains at least security checks, and trigger it before pushing the code into your repository or deploying the architecture.
* Create versions frequently. It saves you many troubles as you can rollback easily to any specific point-in-time copy.
* Always update the status of your architecture.


# Terraform files

### Overview

When you create your architecture, <mark style="color:$primary;">**Brainboard**</mark> automatically and instantly generates a **Terraform** code for your infrastructure.

{% hint style="info" %}
This code is stored in different files according to the best practices of **Terraform.**
{% endhint %}

### Files structure

By default, if you don't rename or change the generated files, you have the following ones:

1. **main.tf**: contains all the definitions of resources and their configuration. See how you can change or rename it below.
2. **outputs.tf**: contains the output variables.
3. **providers.tf**: contains the definition of <mark style="color:$primary;">**`terraform`**</mark> block and the providers.
4. **terraform.tfvars**: contains **only** the values of the variables if defined.
5. **variables.tf**: contains the definition of variables and their blocks.
6. **locals.tf**: contains the definition of **Terraform** <mark style="color:$primary;">**`locals`**</mark>.
7. **backend.tf**: contains the configuration of the remote backend.

### Create a new Terraform file

To create a new **Terraform** file that contains some resources:

1. Using click and drag, select the resource you want to put in the same file and right-click to open the menu. Select  <mark style="color:$primary;">**`Move to file`**</mark>.
2. On the <mark style="color:$primary;">**Edit terraform file name**</mark> modal, assign a name <mark style="color:red;">**(without .tf extension**</mark>) to the new file you are about to create. Click <mark style="color:$primary;">**`Save`**</mark>.&#x20;

<figure><img src="/files/UsTzCv0Bsmg2klM8gbig" alt=""><figcaption></figcaption></figure>

Once the file is created, it will be visible in the list of **Terraform** files in the right menu. Or, you can also access the newly created **Terraform** file using the **hamburger icon** given at the bottom next to the right pane.&#x20;

<figure><img src="/files/0uE7lBeQGLwFnEjNGVSX" alt=""><figcaption></figcaption></figure>

### Rename existing Terraform file

To rename an existing file:

1. Click the <mark style="color:$primary;">**hamburger icon**</mark> at the bottom right to view the list of available **Terraform** files.&#x20;
2. Click on the file that you want to rename.&#x20;
3. Edit the file name as per your requirement.&#x20;
4. Click the <mark style="color:$primary;">**tick mark icon**</mark> given next to the editable field. The Terraform file name will be updated accordingly.&#x20;

<figure><img src="/files/mYB7AmcjGqZLpPed1uDi" alt=""><figcaption></figcaption></figure>

1. Rename it and save.

### Delete a Terraform file

To delete an existing file:

1. Click on the <mark style="color:$primary;">**hamburger icon**</mark> to display the list of existing **Terraform** files in your architecture.&#x20;
2. Click on the <mark style="color:$primary;">**bin icon**</mark> next to the unwanted file.&#x20;
3. On the <mark style="color:$primary;">**Delete File**</mark> confirmation popup, enter the complete file name <mark style="color:red;">**(including the .tf extension)**</mark> as instructed.&#x20;
4. Click <mark style="color:$primary;">**`Delete File`**</mark>.

<figure><img src="/files/OHmRM50Za8kCfENecGMT" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
When you delete a group, the resources inside it **will not be deleted**. They will be put back in `main.tf`. To delete them, you need to select and delete them
{% endhint %}

### Add resource into an existing file

To add one or more resources into an existing **Terraform** file, follow these steps:

1. Using click and drag, select the resource/resources you want to put in the same file and right-click to open the menu.&#x20;
2. Select <mark style="color:$primary;">**`Move to file`**</mark>.
3. On the <mark style="color:$primary;">**Edit terraform file name**</mark> modal, select the file from the dropdown list.
4. Click <mark style="color:$primary;">**`Save`**</mark>.&#x20;

<figure><img src="/files/zD0WnSYzR7MOstRPNVq3" alt=""><figcaption></figcaption></figure>

### Remove resource from a file

To remove a resource from an existing **Terraform** file:

1. Select the resource, and **right-click** to open the **shortcut menu.**&#x20;
2. Select <mark style="color:$primary;">**`Move to file`**</mark>.
3. On the <mark style="color:$primary;">**Edit terraform file name**</mark> modal, select <mark style="color:$primary;">**`main`**</mark> from the dropdown list.
4. Click <mark style="color:$primary;">**`Save`**</mark>.

{% hint style="success" %}
The selected file/files will be removed from the **Terraform** file (other than <mark style="color:$primary;">**`main.tf`**</mark>) that contained it/them.
{% endhint %}

<figure><img src="/files/5vQWb4wr363HhSqcqB4F" alt=""><figcaption></figcaption></figure>

### Best practices

{% hint style="warning" icon="lightbulb-gear" %}
Always group resources that are supposed to work together or have the same logic in a separate group / Terraform file.
{% endhint %}

{% hint style="warning" icon="lightbulb-gear" %}
Use explicit names for your **Terraform** files. Usually, there are **two** conventions of naming:

* **Infrastructure base naming:** <mark style="color:$primary;">**`vpc.tf`**</mark>, <mark style="color:$primary;">**`db.tf`**</mark>
* **Application base naming:** <mark style="color:$primary;">**`microservice1.tf`**</mark>, <mark style="color:$primary;">**`backend.tf`**</mark>
  {% endhint %}


# Readme file

### Description

The <mark style="color:$primary;">**`readme`**</mark> file refers to a text file that provides information about the architecture, its features, requirements, installation instructions, and usage instructions.

{% hint style="info" %}
It's an important component as it serves as the first point of reference for users.
{% endhint %}

When you [create a new architecture,](/getting-started/fast-track) a blank **README** file is created with it by default. You can edit it as you like.&#x20;

To access the **README** file of your architecture, click on the **file** icon (📄) available next to the **help icon** in the right panel.&#x20;

<figure><img src="/files/WasNV8vNbJA7cDZTZ7u9" alt=""><figcaption></figcaption></figure>

### Edit README file

To add information and edit the **README** file, just open the editor and add the details.

Brainboard lets you write a **Markdown** document and generates its **HTML** representation, making it super easy for you and your team to read.

To preview the **HTML** version of your file, switch to the <mark style="color:$primary;">**`Preview`**</mark> tab on the <mark style="color:$primary;">**`Readme.md`**</mark> window.&#x20;

<figure><img src="/files/ZWSLNeqCWOqQRcbV9omo" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/9lTXVbwSvJjCITzBkK9t" alt=""><figcaption></figcaption></figure>

### Visibility of the README file

* The **README** file will be displayed on the templates catalogue.
* The **README** file will be pushed to git when doing a pull request.
* The **README** file will be cloned along with the design of your architecture.

### Best practices

A good **README** file typically includes the following information:

{% hint style="success" %}
**Project description:** A brief overview of the architecture, its purpose, and its key features.
{% endhint %}

{% hint style="success" %}
**Usage instructions:** A step-by-step guide on how to use the architecture, including any variables and configuration settings.
{% endhint %}

{% hint style="success" %}
**Support and contact information:** Details on how to get support or contact the development team, such as through email, forums, or social media.
{% endhint %}

{% hint style="success" %}
**Release notes:** A list of changes, bug fixes, and new features for each release of the architecture.
{% endhint %}


# Architecture Synchronization

### Definition

When managing cloud infrastructures at scale, you may want to keep your environments (e.g. QA, staging, production) close to each other.

You can achieve this by synchronizing an architecture across multiple environments, which means that any modification you do on one environment will be automatically replicated/synchronized with all synced environments, except the values of the variables that are supposed to be specific to each environment.

This allows you to maintain a consistent infrastructure across all your development, testing, and production environments.

### Create a synced environment

Here are the steps you can follow to implement environment sync in <mark style="color:$primary;">**Brainboard**</mark>:

1. Create the design and **Terraform** configuration for a specific architecture within a specific environment, for example: <mark style="color:$primary;">**`Development`**</mark>.
2. Go to [Projects](https://app.brainboard.co/projects) and open the project where your architecture is saved.&#x20;
3. Now, **right-click** on the architecture that you want to sync and click on the <mark style="color:$primary;">**`Duplicate`**</mark> button. It will open the Clone architecture modal for you to enter the following information:&#x20;
   1. **Project:** Select the desired project.
   2. **Target environment:** Add the **target** environment where you want to clone your architecture. For example, <mark style="color:$primary;">**`QA`**</mark>.
   3. **Name:** You can assign a different name to the cloned architecture.&#x20;
   4. **Description (optional)**
   5. **Sync:** Turn this toggle on to keep the source and destination architectures in sync.

<figure><img src="/files/6z63JWHukmi0iOLLXzN4" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The variables values are not synced, so you can use different values for different environments. Refer to the [Variables](/input-output/variables) to know more about the variables
{% endhint %}

### View synced environments

Once the architecture is synced, you see a new <mark style="color:$primary;">**`Sync Information`**</mark> clickable icon in the options bar. When you click on it, you can see all **synchronized environments** for this architecture.

<figure><img src="/files/f537cdBv8T6sDJoB77pE" alt=""><figcaption></figcaption></figure>

### Un-sync environment

To **un-sync** a specific architecture or environment, click on the same **sync** icon available in the options bar. On the <mark style="color:$primary;">**Synced architectures**</mark> modal, click the <mark style="color:$primary;">**`Unsync`**</mark> button for the architecture to unlink it from the synchronized environments. On the confirmation popup, click the <mark style="color:$primary;">**`Unsync architecture`**</mark> button to confirm the unsyncing action.&#x20;

<figure><img src="/files/Hv244ntui0AgHCU8FW3r" alt=""><figcaption></figcaption></figure>

### Best practices

{% hint style="success" %}
Use this process to apply changes to all environments consistently.&#x20;

For example, you might use the <mark style="color:$primary;">**Brainboard**</mark> **CI/CD** engine to apply different pipelines to different environments while keeping the design of the cloud architecture consistent through all environments.

Refer to the [CI/CD Engine](/automation/ci-cd-designer) to learn more about it.
{% endhint %}

{% hint style="success" %}
Use **variables** and other **configuration options** to customize each environment as needed.&#x20;

For example, you might use different values for variables like the number of instances or the size of a database depending on the environment.
{% endhint %}

{% hint style="info" %}
By using <mark style="color:$primary;">**Brainboard**</mark> to implement environment sync, organizations can ensure that their infrastructure is consistent across different environments, reducing the risk of <mark style="color:orange;">**drift**</mark>**,** <mark style="color:red;">**configuration errors**</mark> and <mark style="color:green;">**improving overall reliability.**</mark>
{% endhint %}


# Remote backend

### Definition

The <mark style="color:$primary;">**remote backend**</mark> is a storage that hosts the **Terraform** state of your cloud infrastructure after it is provisioned.

<mark style="color:$primary;">**Brainboard**</mark> uses **Terraform** as the provisioning engine, and so the concept of the <mark style="color:$primary;">**remote backend**</mark> comes from the configuration of **Terraform** that allows you to specify which storage system you want to use and how to access it.

{% hint style="info" %}
The remote backend configuration can be set up at two levels:

1. Global
2. Architecture level
   {% endhint %}

## Global

There are two paths under your [account settings](https://app.brainboard.co/settings/account) in <mark style="color:$primary;">**Brainboard**</mark> that you can follow to configure the remote backend at the global level.

1. Through the [Organization](https://app.brainboard.co/settings/organization) page.
2. Through the [Integrations](https://app.brainboard.co/settings/integrations) page.

### Organization page

Navigate to the **Infrastructure as Code Backend** section on this [page](https://app.brainboard.co/settings/organization). Here, you can select or add the desired remote backend by using the **Backend configuration** field.

{% hint style="info" %} <mark style="color:$primary;">**Brainboard**</mark> is the **default** backend when you don't specify one.
{% endhint %}

{% hint style="success" %} <mark style="color:$primary;">**Brainboard**</mark> stores the **Terraform** state in its cloud storage, which helps you stay protected as we isolate by default the state of every architecture.
{% endhint %}

If you want to add a new configuration, simply click the <mark style="color:$primary;">**`Add new configuration`**</mark> option that appears in the dropdown menu of the **Backend configuration** field. It will navigate you to the <mark style="color:$primary;">**New backend configuration**</mark> page, which is exactly the same as the one that opens when you add a new **Terraform configuration** through the[ Integrations page](https://app.brainboard.co/settings/integrations).

<figure><img src="/files/TM3ctT16aad1rem3bduf" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you use your own **S3** or **blob storag**e remote backend, it means that by default, all the states will be stored in your own infrastructure.
{% endhint %}

### Integrations page

1. On the [Integrations page](https://app.brainboard.co/settings/integrations), click on the <mark style="color:$primary;">**Terraform backend**</mark> section.
2. Then, click <mark style="color:$primary;">**`Add configuration`**</mark> on the [Terraform backend](https://app.brainboard.co/settings/integrations/terraform-backend) page.
3. On the[ New backend configuration page](https://app.brainboard.co/settings/integrations/terraform-backend/create), you will have the option to select from the available supported backend options:
   1. Azure blob storage
   2. AWS S3 bucket
   3. Google Cloud Storage
   4. Terraform cloud
   5. HTTP

<figure><img src="/files/RRKa7XEHkO4oEY666qRV" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
If you use a different backend from the supported ones, please reach out to our support team.
{% endhint %}

## Architecture level

You can specify a different remote backend at the architecture level, giving you more control over where you want to store the state files for any given architecture.

To specify a remote backend for the architecture:

1. Open your architecture canvas.
2. Click the **settings icon** in the top navigation bar.
3. On the Architecture settings page, you can configure the backend using the <mark style="color:$primary;">**Infrastructure as Code Backend**</mark> section. Follow the same steps as mentioned before for [AWS S3](#id-2.-aws-s3-bucket), [Azure blob storage](#id-2.-azure-blob-storage) or [Brainboard backend](#id-1.-brainboard).

<figure><img src="/files/Q0Dfuc66LfzAAw8I0dpt" alt=""><figcaption></figcaption></figure>

## Supported backends

{% hint style="info" %}
Either you specify a **remote backend** (other than <mark style="color:$primary;">**Brianboard**</mark>) at the **global** or **architecture level**, the same [New backend configuration](https://app.brainboard.co/settings/integrations/terraform-backend/create?) page is used.

**Path:** <mark style="color:$primary;">Settings</mark> > <mark style="color:$primary;">Integrations</mark> > <mark style="color:$primary;">Terraform backend</mark> > <mark style="color:$primary;">Add new configuration</mark>
{% endhint %}

{% hint style="warning" icon="lightbulb-gear" %}
You can override the remote backend of a **specific architecture** in its settings page, as explained under[#architecture-level](#architecture-level "mention").
{% endhint %}

{% hint style="success" %}
Once the configuration is done, click on <mark style="color:$primary;">**`Save and close`**</mark> button given at the bottom right corner of the **New backend configuration** page to save the changes.
{% endhint %}

### 1. Brainboard

Brainboard is the default backend, which can be set up as a global backend using the [#organization-page](#organization-page "mention")or at the [#architecture-level](#architecture-level "mention").

### 2. Azure blob storage

Configuring the **Azure blob storage** as the backend in <mark style="color:$primary;">**Brainboard**</mark> means that the **Terraform** state of all your architectures will be stored in the specified **blob storage**.

When you specify the **Azure blob storage**, <mark style="color:$primary;">**Brainboard**</mark> stores the **Terraform** state of every architecture in a separate file that has the **UUID** of the architecture as a name.

On the [**New backend configuration** page](https://app.brainboard.co/settings/integrations/terraform-backend/create), navigate to the **Azure Blob Storage** tab and enter the following information:

* **Name** of the configuration
* **Resource group**
* **Storage account name**
* **Storage account key:** You can create a new access key following this [Azure documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal)
* **Container name**

{% hint style="warning" %}
When you specify the storage **container name**, if the container doesn't exist, <mark style="color:$primary;">**Brainboard**</mark> will create a new one with the name you enter. To do so, it uses the default **AzureRM** credentials, so make sure these credentials have the rights to create a new storage container in the selected storage account.
{% endhint %}

* **Use Microsoft Entra ID:** Enabling this will use the architecture cloud provider connection to access the storage account. Conflicts with the storage account key.
* **Create more**

<figure><img src="/files/xSaupMqffuItNH0H2nf3" alt=""><figcaption></figcaption></figure>

### 2. AWS S3 bucket

Specifying the **AWS S3** bucket as a backend in <mark style="color:$primary;">**Brainboard**</mark> means the **Terraform** state of all your architectures will be stored in the bucket you specify.

When you specify the **S3** bucket, <mark style="color:$primary;">**Brainboard**</mark> stores the **Terraform** state of every architecture in a separate file that has the **UUID** of the architecture as a name.

On the [**New backend configuration** page](https://app.brainboard.co/settings/integrations/terraform-backend/create), navigate to the **AWS S3 Bucket** tab and enter the following information:

* **Credential**
* **Name** of the configuration
* **Bucket name**

{% hint style="warning" %}
When you specify the **bucket name**, if the bucket doesn't exist, <mark style="color:$primary;">**Brainboard**</mark> will create a new one with the name you enter. To do so, it uses the default **AWS credentials**, so make sure these credentials have the rights to create a new bucket.
{% endhint %}

* **Region**
* **Dynamodb table**

<figure><img src="/files/vHLaVSyxvhRRwxb6HhGb" alt=""><figcaption></figcaption></figure>

### 3. Google Cloud Storage

<mark style="color:$primary;">**Brainboard**</mark> enables you to use **Google Cloud Storage** as a remote backend to host your **Terraform** states of all your architectures.

On the [**New backend configuration** page](https://app.brainboard.co/settings/integrations/terraform-backend/create), navigate to the **Google Cloud Storage** tab and enter the following information:

* **Credential**
* **Name** of the configuration
* **Bucket name**
* **Project**

<figure><img src="/files/wY5gCgyAqz2CKnNGfWrh" alt=""><figcaption></figcaption></figure>

### 4. Terraform Cloud backend

<mark style="color:$primary;">**Brainboard**</mark> enables you to use **Terraform Cloud** as a remote backend to host your **Terraform** states of all your architectures.

On the [**New backend configuration** page](https://app.brainboard.co/settings/integrations/terraform-backend/create), navigate to the **Terraform Cloud** tab and enter the following information:

* **Name** of the configuration
* **Hostname**
* **Organization** name
* **Workspace** name
* The **token** to authenticate

<figure><img src="/files/MLTWruXTkXqvBbOnMKve" alt=""><figcaption></figcaption></figure>

### 5. HTTP

<mark style="color:$primary;">**Brainboard**</mark> enables you to use **HTTP** as a remote backend to host your **Terraform** states of all your architectures.

On the [**New backend configuration** page](https://app.brainboard.co/settings/integrations/terraform-backend/create), navigate to the **Terraform Cloud** tab and enter the following information:

* **Name** of the configuration
* **Address**
* **Lock address**
* **Unlock address**
* **Update method**
* **Lock method**
* **Unlock method**
* **Username**
* **Password**
* **Skip certificate verification** on/off toggle

<figure><img src="/files/Zjec2ijUBt5nqzyFBv67" alt=""><figcaption></figcaption></figure>

## Access

To access the remote backend, <mark style="color:$primary;">**Brainboard**</mark> uses the default cloud provider credentials that you provide in the [credentials page](https://app.brainboard.co/settings/integrations/cloud-providers), so make sure that these credentials have the right to access the storage.

Refer to the [data management](/security/data) page if you want to understand what information is manipulated and/or stored by Brainboard.

## State migration

To migrate your **Terraform** state into <mark style="color:$primary;">**Brainboard**</mark>, you have two options:

1. **Use&#x20;**<mark style="color:$primary;">**Brainboard**</mark>**&#x20;backend:** In this case, you need to upload your state files when you import your **Terraform** files. <mark style="color:$primary;">**Brainboard**</mark> will automatically detect the state file and put it in our storage.
2. **Use your remote backend (AWS S3 or Azure blob storage):**
   * Configure the remote backend in <mark style="color:$primary;">**Brainboard.**</mark> Follow the steps for [AWS S3](#id-2.-aws-s3-bucket) or [Azure Blob Storage](#id-2.-azure-blob-storage).
   * In the remote backend storage that you configured, create a folder that has a name as that of the architecture **UUID**.
   * Put your state in the folder you just created.
   * Test in <mark style="color:$primary;">**Brainboard**</mark> by launching a ***Terraform Plan*** from the design area of your architecture.


# Template

### Description

A cloud architecture template in <mark style="color:$primary;">**Brainboard**</mark> is a pre-designed and standardized architecture that can be used to create and deploy cloud infrastructure. It includes a set of guidelines and best practices for designing, building, and managing cloud infrastructure.

The templates typically provide the design and **Terraform** code of the architecture and include details on the components that make up the infrastructure, such as virtual machines, storage, networks, and security.

These templates are designed to be reusable, making it easier and quicker to implement and manage cloud infrastructure. They can help organizations to achieve consistent deployment patterns, enforce governance policies, and reduce time and effort required to deploy cloud infrastructure.

{% hint style="info" %}
Cloud architecture templates include **AWS Well-Architected Framework, Google Cloud Architecture, Microsoft Azure Architecture**, and the **OpenStack Architecture.** They are created to help organizations to build and manage secure, scalable, and cost-effective cloud infrastructure.
{% endhint %}

### Types of templates

In <mark style="color:$primary;">**Brainboard**</mark>, you can find two types of templates:

| Organization                                                                                                                                                                                                                                                                  | Public                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>These are templates that are visible and can be used only within the organization in different projects. </p><p>The organization templates can be used when teams want to share their templates and reuse them in other projects or architectures of the organization.</p> | These are usually templates published by the <mark style="color:$primary;">**Brainboard**</mark> team and are verified templates that are built by cloud architects who maintain and update them regularly. |

### Create a template

To publish your architecture as a template, you can navigate to the architectures directory and follow the steps below:

1. Go to [Projects](https://app.brainboard.co/projects) in your <mark style="color:$primary;">**Brainboard**</mark> account, and navigate to the architecture that you want to publish as a template.&#x20;
2. **Right-click** on the architecture and then click <mark style="color:$primary;">**`Publish as template`**</mark> in the context menu.&#x20;
3. On the <mark style="color:$primary;">**`Publish as Template`**</mark> modal, enter the following information:&#x20;
   1. Choose the **visibility** of the template; it can be either <mark style="color:$primary;">**`organization`**</mark> or <mark style="color:$primary;">**`public`**</mark>.
   2. Choose a **new name** for the template.
   3. You can enter the **description** if you want.&#x20;
4. Click the <mark style="color:$primary;">**`Publish as Template`**</mark> button.&#x20;

{% hint style="danger" %}
Make sure to remove all sensitive information, such as passwords, from the architecture
{% endhint %}

<figure><img src="/files/gdSRhEXA2pRndMcY6SC3" alt=""><figcaption></figcaption></figure>

### Use a template

Here are the steps to use a cloud architecture template:

1. Open the Cloud infrastructure templates catalogue.

   ![cloud-template-catalog.png](/files/7NdLYGe7KChGQO9FAOTU)
2. Choose a template: Select a template that meets your requirements and aligns with your business goals. You can filter the search by using a keyword, the cloud provider, and the level either `public` or `organization`.
3. Review the template: Study the template description in detail and understand the components. Make sure that the components in the template align with your requirements.
4. Clone the template into your project. You can either:

   * **Clone the template into a new architecture.** This option would create a new architecture and clone all the components of the template into the new architecture
   * **Copy the template into the current architecture.** This option would copy the design and terraform code and add it to your current architecture.

   ![use-templates-catalog.png](/files/zxXocgDH12ony7YPB3qf)
5. Customize the template: Modify the template to fit your specific needs. This may include changing the configurations, adding or removing components, changing variables etc.
6. Deploy the template: Once you have tested the template and made any necessary changes, you can deploy it to your environment.

### Modify a template

After you publish a template, you can find it in the templates' project.

![templates-catalog.png](/files/pJrKLuZGSUxOdcxcFPB8)

1. If you need to modify the template, you can open and modify the template by selecting the template that you need and making the changes.
2. By clicking on the second and third buttons next to the template name, you can create a new template from the current template or clone the template.
3. If you need to modify the template's details, you can click on the `pen` next to the architecture name and add the information :

   ![template-detail.png](/files/wVOB69GcvkI7v0cC3CHD)

   * **Name:** This is the name that will be displayed in the template catalog.
   * **Status:** You can choose the status of the template from the values below. If you are working in a team and the template needs approval before being published, then you can choose the status `reviewing` or `approved`.

     <figure><img src="/files/RPvZ1NFyQW4zhjxSczZn" alt=""><figcaption></figcaption></figure>
   * **Description:** Add a brief description of the template.
   * **Template visibility:** You can choose the visibility of the template.
   * **Tag:** Add the tags so that it is easier to search for it when needed by the team.
   * **Snapshot URL:** Add the image that you want to be displayed in the templates catalog.
4. If you need to delete the template, select the template and click on the `bin` icon next to the templates project.


# Cloud providers


# Supported cloud providers

### Cloud provider definition

A **Terraform cloud provider** is a plugin that allows **Terraform** to interact with a specific cloud provider's API to create, manage, and delete resources. Each cloud provider has its own set of resources and data sources that can be used to define and manage infrastructure with **Terraform.**

You can use the provider block to specify which cloud provider you are using and configure its settings.

{% hint style="info" %}
This block is typically placed at the top of a **Terraform** configuration file, and you can specify multiple providers to manage resources across multiple cloud providers
{% endhint %}

<mark style="color:$primary;">**Brainboard**</mark> supports the following cloud providers:

### Azure (Azure Resource Manager)

<mark style="color:$primary;">**`AzureRM`**</mark> is the **Terraform** provider for **Azure Resource Manager (ARM)**, which is the service that allows you to **manage** Azure resources.

{% hint style="success" %}
It provides **Terraform** with the necessary API calls to interact with Azure's API and create, manage, and delete resources within your Azure account.
{% endhint %}

{% hint style="success" %}
When you use the **AzureRM** provider in **Terraform**, you can *<mark style="color:$primary;">define resources</mark>* such as *<mark style="color:blue;">virtual machines, storage accounts, and virtual networks</mark>*, and use **Terraform** to *<mark style="color:$primary;">create, update,</mark> and <mark style="color:$primary;">delete</mark>* those resources in **Azure.**
{% endhint %}

{% hint style="info" %}
Refer to the [credential page](/settings/integrations/cloud-providers/azure) to understand how to connect <mark style="color:$primary;">**Brainboard**</mark> with your Azure environments.
{% endhint %}

### AWS (Amazon Web Services)

The <mark style="color:$primary;">**`AWS`**</mark> provider for **Terraform** is a plugin that allows **Terraform** to interact with the **AWS API** to create, manage, and delete resources within an **AWS** account.

{% hint style="success" %}
It provides **Terraform** with the necessary API calls to *<mark style="color:$primary;">create, update,</mark> and <mark style="color:$primary;">delete</mark>* **AWS** resources such as *<mark style="color:blue;">EC2 instances, S3 buckets,</mark>* *and* *<mark style="color:blue;">RDS databases.</mark>*
{% endhint %}

{% hint style="info" %}
Refer to the [credential page](/settings/integrations/cloud-providers/aws) to understand how to connect <mark style="color:$primary;">**Brainboard**</mark> with your AWS environments.
{% endhint %}

### OCI (Oracle Cloud Infrastructure)

<mark style="color:$primary;">**`Oracle Cloud Infrastructure`**</mark> provider is a plugin that allows **Terraform** to interact with the **Oracle Cloud Infrastructure (OCI) API** to create, manage, and delete resources within an **OCI** account.

{% hint style="success" %}
It provides **Terraform** with the necessary **API calls** to *<mark style="color:$primary;">create, update,</mark> and <mark style="color:$primary;">delete</mark>* OCI resources such as *<mark style="color:blue;">Compute instances, Virtual Cloud Networks,</mark> and <mark style="color:blue;">Block Volumes.</mark>*&#x20;

It also allows managing other resources that are not directly related to **OCI**, such as *<mark style="color:blue;">DNS records</mark>* and others.
{% endhint %}

{% hint style="info" %}
Refer to the [credential page](/settings/integrations/cloud-providers/oci) to understand how to connect <mark style="color:$primary;">**Brainboard**</mark> with your OCI environments.
{% endhint %}

### GCP (Google Cloud Platform)

<mark style="color:$primary;">**`Google Cloud Platform`**</mark> provider for **Terraform** is a plugin that allows **Terraform** to interact with the **Google Cloud API** to  *<mark style="color:$primary;">create, manage,</mark> and <mark style="color:$primary;">delete</mark>* resources within a **GCP** project.

{% hint style="success" %}
It provides **Terraform** with the necessary **API calls** to *<mark style="color:$primary;">create, update,</mark> and <mark style="color:$primary;">delete</mark>* **GCP** resources such as **Compute Engine** **instances**, **Cloud Storage buckets**, and **Cloud SQL databases.**
{% endhint %}

{% hint style="info" %}
Refer to the [credential page](/settings/integrations/cloud-providers/gcp) to understand how to connect <mark style="color:$primary;">**Brainboard**</mark> with your **GCP** environments.
{% endhint %}

### Scaleway

<mark style="color:$primary;">**`Scaleway`**</mark> provider for **Terraform** is a plugin that allows **Terraform** to interact with the **Scaleway API** to *<mark style="color:$primary;">create, manage,</mark> and <mark style="color:$primary;">delete</mark>* resources within a **Scaleway** account.

{% hint style="success" %}
It provides **Terraform** with the necessary **API calls** to *<mark style="color:$primary;">create, update,</mark> and <mark style="color:$primary;">delete</mark>* **Scaleway** resources such as *<mark style="color:blue;">Compute instances, Volumes,</mark> and <mark style="color:blue;">Networks.</mark>*
{% endhint %}

### Providers versions

Every **Terraform** cloud provider has different versions for both its resources and data sources.

You can select any version from the list of versions:

<figure><img src="/files/pqkM15e9sBmrfwG5JMQO" alt=""><figcaption></figcaption></figure>

When you select a specific version, <mark style="color:$primary;">**Brainboard**</mark> loads all the resources of this version and the <mark style="color:$primary;">**Resource Configuration**</mark> panel of every resource will contain the parameters available in the selected version.

{% hint style="warning" %}
When selecting a different version, always do a <mark style="color:$primary;">**`plan`**</mark> to make sure that the code is valid, as most often parameters are updated between versions and some resources may be added or deleted
{% endhint %}


# Customize provider configuration

There are many scenarios when customizing a cloud provider block is needed:

* **Multi-cloud deployments**: If you have resources in different cloud providers, you can use multiple providers in Terraform to manage those resources together.
* **Hybrid deployments**: If you have resources in both a cloud provider and on-premises, you can use multiple providers in Terraform to manage those resources together.
* **Third-party services:** If you are using services provided by third-party providers, you can use their provider in Terraform to manage those resources.

{% hint style="info" %}
For example, you might be using a service like **Cloudflare** for **DNS**, and you can use the **Cloudflare** provider in **Terraform** to manage those resources
{% endhint %}

* **Managing different environments**: If you want to manage different environments (e.g. development, staging, production) with different providers, you can use multiple providers in Terraform to manage those resources together.
* **Adding new resources from an unsupported provider**: If you are adding new resources to your infrastructure, you may need to add a new provider if the resources are provided by a different provider than the existing resources.
* **Updating provider version:** If the provider version you are using is not supported by the provider, you will need to update the provider version in the providers block to a supported version.
* **Modifying provider configuration**: If you have to modify the provider configuration, such as adding a region, or updating endpoint URLs, you will have to modify the providers block.
* **Access control**: If you have to restrict access to certain provider resources, you may have to modify the providers block to add authentication or authorization configuration.

To customize the provider block, you need to go to the providers list in the ***Leftbar***.&#x20;

1. In the dropdown menu, click the <mark style="color:$primary;">**`Custom configuration`**</mark> button to customize the desired **Terraform** and provider configuration block.
2. Turn on the toggle <mark style="color:$primary;">**`I want to customize my Terraform & provider configuration block`**</mark>.&#x20;
3. After you make the changes that you need, click <mark style="color:$primary;">**Apply**</mark> to save the changes.

<figure><img src="/files/dGBGq1YJIKpJC8MRYe6n" alt=""><figcaption></figcaption></figure>


# Unsupported cloud providers

### Description

**Terraform** supports a wide range of providers, including popular cloud providers, infrastructure providers, and SaaS providers.

They can be categorized as:&#x20;

{% hint style="success" icon="1" %}
**Official** providers are owned and maintained by <mark style="color:blue;">**HashiCorp**</mark>**.**
{% endhint %}

{% hint style="success" icon="2" %}
**Partner** providers are written, maintained, validated and published by third-party companies against their own APIs.
{% endhint %}

{% hint style="success" icon="3" %}
**Community** providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.
{% endhint %}

Besides the providers that are supported by <mark style="color:$primary;">**Brainboard**</mark> *<mark style="color:green;">(Azure, AWS, GCP, OCI, Scaleway)</mark>*, you can use all the other providers by following these steps:

1. **Add the configuration** for the cloud providers in the cloud provider configuration.
2. **Add a new resource** for that provider by using custom resources.

To illustrate, let's consider <mark style="color:blue;">**Palo Alto**</mark>, a Terraform provider not supported by <mark style="color:$primary;">**Brainboard**</mark>, and see how we can use it.

### Palo Alto Terraform provider

The <mark style="color:blue;">**Palo Alto Networks Terraform**</mark> provider is a plugin for **Terraform** that allows you to manage <mark style="color:blue;">**Palo Alto Networks**</mark> resources, such as *<mark style="color:blue;">firewalls</mark>*, in Terraform. The provider provides a set of **Terraform** resources that map to corresponding <mark style="color:blue;">**Palo Alto Networks**</mark> resources, allowing you to manage your network infrastructure as code.

### Cloud Provider Configuration

To configure the <mark style="color:blue;">**Palo Alto Networks**</mark> provider, you need to follow these steps:

#### 1. Configure the provider

In the ***left bar*****,** click on the drop-down menu next to the cloud provider icon, and click the <mark style="color:$primary;">**`Custom configuration`**</mark> button. Enable the toggle on the <mark style="color:$primary;">**Customer Terraform provider definition**</mark> modal.&#x20;

<figure><img src="/files/U5tdYOMKOYq7hbZp27lx" alt=""><figcaption></figcaption></figure>

In the custom provider block, you'll need to configure the <mark style="color:blue;">**Palo Alto Networks**</mark> provider by specifying the required parameters. This may include the **API** key or other credentials to connect to the <mark style="color:blue;">**Palo Alto Networks**</mark> platform. A sample provider configuration block could look like this:

```hcl
provider "paloalto" {
  api_key = "<your-api-key>"
}
```

#### 2. Add a resource

Once the provider is configured, you can add a resource in <mark style="color:purple;">**Brainboard**</mark>. For example, you could create a *<mark style="color:cyan;">firewall</mark>* rule in <mark style="color:blue;">**Palo Alto Networks**</mark> like this:

1. At the bottom of the *<mark style="color:$primary;">**Leftbar**</mark>*, you can find the custom resources. This is a block where you can add **Terraform** resources that <mark style="color:$primary;">**Brainboard**</mark> does not yet support.

<figure><img src="/files/42AlMJCAMD2ZbihJnYYP" alt="" width="563"><figcaption></figcaption></figure>

2. Drag and drop the custom resource, open its configuration and complete the information:&#x20;

* **Icon:** Add a custom icon by clicking on the icon at the top of the configuration panel.
* **Block Type:** Add either resource if you want to provision a new resource, or data.
* **Resource Type:** Add the type of the new resource from the cloud provider. In this example, it is <mark style="color:blue;">**`paloalto_security_rule`**</mark>.
* **Resource name:** Add a name for your new resource.
* **Terraform code of the resource:** Add the resource code and configuration into this field.

<figure><img src="/files/hiotUoP8TuljGdY3eAVI" alt=""><figcaption></figcaption></figure>

After finishing these steps, you can use the resource as other supported resources in <mark style="color:$primary;">**Brainboard**</mark> and test it by running the **Terraform plan/apply** command to create or update the resources in the <mark style="color:blue;">**Palo Alto Networks**</mark> platform.


# Terraform / OpenTofu


# Modules


# Module

### Description

<mark style="color:$primary;">**Modules**</mark> are self-contained packages of **Terraform** configurations that are managed as a group. <mark style="color:$primary;">**Modules**</mark> allow you to organize your **Terraform** code and reuse it across multiple projects, making it easier to manage and maintain your infrastructure as code.

There are two types of **Terraform** modules:

{% hint style="success" icon="1" %}
**Root modules:** These are the main **Terraform** configurations that define your infrastructure. The root module is the top-level module in your **Terraform** configuration, and it calls other **Terraform** modules as needed.
{% endhint %}

{% hint style="success" icon="2" %}
**Child modules:** These are **Terraform** modules that are called by the root module. Child modules encapsulate a portion of your infrastructure, making it easier to manage and maintain.
{% endhint %}

When you create a **Terraform** module, you can use inputs and outputs to define the expected input and output values of the module:

* <mark style="color:$primary;">**`Inputs`**</mark> allow you to pass parameters into the module, making it more flexible and reusable.
* <mark style="color:$primary;">**`Outputs`**</mark> allow you to expose values from the module so that they can be used by other **Terraform** modules.

<figure><img src="/files/bHm92e2GhiBAFekau2OO" alt=""><figcaption></figcaption></figure>

### Modules structure

The basic structure of a **Terraform** module includes:

* <mark style="color:$primary;">**`Variables`**</mark>: these are values that are passed into the module when it is called.
* <mark style="color:$primary;">**`Resources`**</mark>: The main part of a module is the collection of Terraform resources that are defined within it. These resources are used to create the infrastructure.
* <mark style="color:$primary;">**`Outputs`**</mark>: These are values that are returned by the module when it is called. These outputs can be used by other modules or in the root module of the Terraform configuration.

<figure><img src="/files/LdQPGhp5PufhheCmIakV" alt=""><figcaption></figcaption></figure>

### Best practices

When using modules, these best practices make your life easier:

{% hint style="warning" icon="lightbulb" %}
**Verify the source**: Before using a module from the Terraform Registry, verify the source to ensure that it's reputable and secure.
{% endhint %}

{% hint style="warning" icon="lightbulb" %}
**Review the documentation**: Review the documentation of the module to ensure that it meets your requirements and to understand how it can be used in your configuration.
{% endhint %}

{% hint style="warning" icon="lightbulb" %}
**Use version control**: Use version control to keep track of changes to the module, and make sure to use a specific version of the module in your configuration so that you are aware of any breaking changes.
{% endhint %}

{% hint style="warning" icon="lightbulb" %}
**Test the module**: Test the module thoroughly before using it in production to ensure that it works as expected and to catch any bugs or errors.
{% endhint %}


# Import modules

## Overview

<mark style="color:$primary;">**Brainboard**</mark> allows you to import your modules from any valid source supported by **Terraform**, organize them and keep yourself *DRY (don't repeat yourself)*.

There are many publicly available **Terraform** modules on platforms like the **Terraform** **Registry** or **GitHub** that you can use to quickly get started with your infrastructure.

Let's have a look at how we can import modules in <mark style="color:$primary;">**Brainboard**</mark>.

## Add modules as a block definition

1. You can add modules by clicking on the <mark style="color:$primary;">**`Import`**</mark> button.&#x20;

<figure><img src="/files/Z1S33BlcJUW2o9F9O4ry" alt=""><figcaption></figcaption></figure>

It will add a module as a black box, where Brainboard generates its block definition, but it doesn't show you the resources inside.

Add the information for the *<mark style="color:$primary;">name, source</mark>* and *<mark style="color:$primary;">custom icon</mark>*.

<figure><img src="/files/qDuMYZh87yLV913dqhmu" alt="" width="563"><figcaption></figcaption></figure>

### Specifying source of import

#### **1. From registry**

The **Terraform** Registry is a centralized repository for **Terraform** modules. It allows **Terraform** users to easily find and use Terraform modules for various cloud providers and other infrastructure resources.

<figure><img src="/files/2Nhxr3DjadXkR22m3Cul" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
When you import from the <mark style="color:$primary;">**registry**</mark>, you can add the information for the <mark style="color:$primary;">**`namespace/module_name/provider_name`**</mark>.
{% endhint %}

{% hint style="success" icon="lock" %}
If your **Terraform** module is hosted in a private registry, toggle <mark style="color:$primary;">**`Use terraform registry credentials`**</mark> and select the credentials you want to use.
{% endhint %}

Refer to [Terraform Registry Credentials](/data/terraform-opentofu/terraform-modules/terraform-registry-credentials) to learn how to manage your **Terraform** registry credentials.

<figure><img src="/files/dji7BXf9b1Tpgwk1ILvC" alt="" width="563"><figcaption></figcaption></figure>

#### **2. From Git**

Many **Terraform** modules are hosted on **GitHub**, either as standalone repositories or as part of a larger project.

{% hint style="success" %}
If you have private modules, you can store them in a private repository, such as a private **GitHub** repository or an internal repository.&#x20;

When the repo that you want to import is private, you also need to specify the credentials by turning ont the toggle <mark style="color:$primary;">**`My repo is private and requires credentials`**</mark>.

You can specify a service *<mark style="color:$primary;">GitHub</mark>*<mark style="color:$primary;">,</mark> <mark style="color:$primary;"></mark>*<mark style="color:$primary;">Azure DevOps</mark>*<mark style="color:$primary;">,</mark> <mark style="color:$primary;"></mark>*<mark style="color:$primary;">Bitbucket</mark>* or *<mark style="color:$primary;">GitLab</mark>*.
{% endhint %}

Refer to [Git Configurations](/settings/integrations/git-configuration/ado) to know more about **Git** configuration.

<figure><img src="/files/HZ9b6RAoB5aIODdYlaTi" alt="" width="563"><figcaption></figcaption></figure>

#### **3. From files**

You can also create your own modules using **Terraform** code and store them as local files and then import them in <mark style="color:$primary;">**Brainboard**</mark>.

<figure><img src="/files/lSKP9xMIq5Cm6etp37Eh" alt="" width="563"><figcaption></figcaption></figure>

### Add modules as an architecture

There are some cases when importing a module as an architecture is useful.

1. When a user wants to have **visibility** on the code and on the resources used by the module.
2. When a user wants to **modify** an existing module and use it later.

To import a module as an architecture, you can go to the top bar menu and click the `+` button to import an architecture.

![Import](/files/ijE2k4ASFaImHQZUZU83)


# Manage module

To manage modules within <mark style="color:$primary;">**Brainboard,**</mark> you can go to the <mark style="color:$primary;">**Modules Catalog**</mark> by clicking on the <mark style="color:$primary;">**`Catalog`**</mark> button under the **Modules** section in the **left bar.**

In this window, you can see and manage all your imported modules and choose which ones you want to have displayed in the modules list in your design area by <mark style="color:$primary;">**`pinning`**</mark> them.

If you want to change the configuration of a module, you can choose one of the modules in the list:

* In the module configuration, you can show the module in the design or remove it from the design by using the <mark style="color:$primary;">**`pin`**</mark> icon.
* You can **edit** the configuration by using the <mark style="color:$primary;">**`pen`**</mark> icon.
* You can delete the module by using the <mark style="color:red;">**`bin`**</mark> icon.

<figure><img src="/files/gbUBiColTbAbWpdEzoIN" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To have a more organized modules list in your design area, only <mark style="color:$primary;">**`pin`**</mark> the modules that are needed for a specific architecture. If you need more modules, you can revisit the modules catalog later and pin them.
{% endhint %}


# Terraform registry credentials

To import **Terraform** modules from a [private registry](https://developer.hashicorp.com/terraform/registry/private), you need to provide the credentials to access the registry.

**Registry** credentials used by **Terraform** require two pieces of information:

* The <mark style="color:$primary;">**hostname**</mark> of your private registry
* The <mark style="color:$primary;">**token**</mark> used to authenticate with the registry

To add new registry credentials, follow these steps:

1. Go to the [Registry credentials page](https://app.brainboard.co/settings/terraform-registry).
2. Click on the <mark style="color:$primary;">**`Create credentials`**</mark> button and fill in the following information on the <mark style="color:$primary;">**Create credentials**</mark> modal.&#x20;
   * **Name:** Name of the credential.
   * **Host:** Terraform registry hostname.
   * **Token:** Terraform registry token.
   * **Scope:**
     * **Organization:** Credentials will be available to all users in the organization.
     * **User (myself):** Credentials will be available only to you.

{% hint style="warning" %}
**Credentials scope** can only be set at creation. You will not be able to change credentials scope after creation.&#x20;
{% endhint %}

3. Click on the <mark style="color:$primary;">**`Create`**</mark> button to save your credentials.

<figure><img src="/files/MoURqTPjA7UPpg4agb1L" alt=""><figcaption></figcaption></figure>


# Use modules

To use a module in your Terraform configuration in Brainboard, you can use the black box module and add it to your schema by dragging and dropping it into the design.

You also need to specify the values for the variables defined in the module.

As an example, we will use a module for naming conventions. This module helps you to keep consistency on your resources names for Terraform. The goal of this module is to easily provide a name for each resource that requires a name in Terraform following the best practices.

1. Drag and drop the module into your schema and open the Resource Configuration panel of the module.

   ![Use module](/files/zOFf0istCRMGZthkZ8zQ)

   The Resource Configuration panel will have all the information for the input and the attributes that the module needs to be used properly as designed.\
   In the Resource Configuration panel, you can also specify the version that you want to use for this module and extra attributes.
2. After you finish with this step, the module is ready to be used in your terraform configuration.
3. Open a resource and use the module to generate the name of the resource. The syntax is *module.module\_name.resource\_type.\[name, name\_unique]*

   ![Call module](/files/4DiIv5hF0BQgAmpk5oo0)


# Disaster recovery

### Definition

**Disaster Recovery (DR)** is a structured, and documented approach that gives organizations the ability to recover and protect their IT infrastructure, data, and operations after a disruptive event, such as natural disasters, cyberattacks, hardware failures, or human errors. It is a critical component of business continuity planning (BCP) and focuses on restoring normal business operations with minimal downtime and data loss.

### DR components

Modern applications and infrastructures require a different DR approach, and part of the planing for a DR strategy in the cloud, is to understand what will be saved and how. This will determine how it will be restored in case of a disaster. There are 2 different components:

1. **Data:** These are the information / data inside the resources. For example, the records inside the database or files inside the storage.

   * This part could be handled either by the native cloud services, simple replication, or dedication solutions to specific workloads.
   * All providers offer backup solutions. For example: Azure backup policy, vault, AWS backup plan...

   Testing the recovery means restoring the data and checking its integrity.
2. **Resources:** This represents the real cloud resources to provision before restoring the data.

   * It is a hard requirement before restoring the data.
   * If you have more resources connected to each other and configured to work with each other, you need to save the complete architecture as a data.

   Restoring this workload requires provisioning cloud resources with exactly the same configuration as the original one.

This means, that before restoring the data in the cloud, you need to first create the resources exactly as it were before. For example: If you have an application that has servers and a database, in order to resume operation before the disaster, you need to, first, create the servers and the database with the same configuration. Then restore the records and files as they were before.

Brainboard is designed to help you:

* Backup and restore your complete architecture: This allows you to restore your resources with their configuration as they are/were in production.
* Build your data backup architectures: Whether you are using native cloud services for backup or external solutions, you can build it as an architecture in Brainboard to be able to backup your data on a regular basis.

{% hint style="info" %}
Accesses, authorizations, link between resources are saved and restored as either cloud architectures, resources or data objects.
{% endhint %}

#### Stateless vs Stateful workloads

It is important to understand the nature of your workloads to build the most effective DR strategy for them:

1. **Stateless workloads:** There is no data to be saved or restored, only provisioning of the resources.
2. **Stateful workloads:** Like databases, that requires the data to be saved and restored later when needed.

This is mainly used to understand how operations will resume, and help understand the order & dependency between resources, if any.

### Disaster recovery steps in Brainboard

Disaster recovery is not just about reacting to incidents, but also proactively preparing for them to safeguard the organization's long-term viability.

Here are the complete steps to build a robust and reliable DR strategy in Brainboard including a continuous checking to make sure the DR environment is always in a deployable state.

1. **Determine the source of the information:** In this step, you determine where is the environment for which you are creating a DR strategy. Brainboard helps either:
   1. **Import from cloud providers:** For workloads that don't have any Terraform / IaC code, Brainboard allows you to import them, generate a design with Terraform code and ultimately build a DR environment for them.

      Refer to the page [Migration](/help-and-faq/enterprise-customers/migration) to understand how to migrate your cloud environment to Brainboard and generate Terraform code for it.
   2. **Import from existing Terraform:** If you already have a Terraform code for your environment, you can easily import it in Brainboard to get started. You can import your Terraform code from either a Git repository or local files.
2. **Make the configuration dynamic:** Once you import your cloud infrastructure, the next step is to make the information that are specific to the DR environment dynamic in Brainboard. This allows you to create a replicas of your production without impacting it.

   You do this by creating variables in the imported architecture and replace the hardcoded values with them:

   1. Create a variable: Click on the `Variable` button in the leftbar to open the variables' page

      <figure><img src="/files/KP4LzlCMRUQdZg8nWxo1" alt=""><figcaption></figcaption></figure>
   2. Create a new variable, give it a name, a description, type and add a value in the value field.

      <figure><img src="/files/tuvWJw5uwOk0HNrrQ8Z4" alt=""><figcaption></figcaption></figure>
   3. Use the variable in the architecture, the generated code should reflect your changes.

      <figure><img src="/files/r6TAxtpP7Fs2RObgWkva" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
When you create a variable, use "value" field, not the "default value" because the default value will be shared with all environments.
{% endhint %}

#### Common customizations:

Here are some of the most common and important information that you may need to change into a dynamic configuration:

1. **Naming conventions:** It is a best practice to have naming conventions for your resources, so you can clearly identify production ones from non-prod or DR. You can do it in Brainboard by creating variables that are part of your convention and use them.

   <figure><img src="/files/8illNGrgKNCAfLYJSeev" alt=""><figcaption></figcaption></figure>
2. **Tagging:** It's also a best practice to have different tags for different purpose. For e.g. you can have the environment as a tag that will be injected in your resource to know which ones are part of the prod and which others are part of the DR environment.
3. **Location:** If the DR environment has to be created in a different location/region, it's better to create a location or region variable and use the right Brainboard container to help you inject it in all resources:

   <figure><img src="/files/eJjtInXO6STgErjgycCG" alt=""><figcaption></figcaption></figure>

   With this configuration, you only have to specify the value of the location of every environment.
4. **Create and synchronize the DR environment:** Now that you have configured the variables and updated your configuration, you click on the name of the architecture in the top left corner and create a synchronize copy of it in the DR environment.
   1. Click on clone architecture button

      <figure><img src="/files/iYGPy75Hs0gft3tvJyM2" alt=""><figcaption></figcaption></figure>
   2. Specify the Disaster recovery as the target environment. If you don't have a disaster recovery folder, create one first.
   3. Very important: Click on "Sync" switch. This will create a copy of your original architecture (in this case production) and keeps it synchronized with your production. Whenever you change the production environment, Brainboard automatically replicates the changes in the DR environment.

      <figure><img src="/files/niUTWyhj0PVZJONNzz35" alt=""><figcaption></figcaption></figure>
   4. Verify that the sync is active: You should have a red button in the options' bar to indicate the sync is in effect:

      <figure><img src="/files/Guu3r5CWTja0eQq6D9E6" alt=""><figcaption></figcaption></figure>

      1. When you click on it, it will show you all the synchronized environments (synced architectures):

         <figure><img src="/files/fZb2dJaP9yUu7u7ldXnm" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**How the sync works:** Once you create a synced architecture, every modification you do in one environment will be automatically replecated into the other environment(s), except the values of the variables that are specific to every environment.

This replication doesn't trigger deployment to give you the flexibility to chose which environment you want to deploy, how and when.

Please refer to page [Architecture Synchronization](/data/data-structure/cloud-architecture/synced-architectures) for more details about this feature.
{% endhint %}

4. **Continuous monitoring & notification:** Now that you configured your DR environment through the synced architecture of your production, you can schedule a CI/CD workflow in Brainboard. This will test if the infrastructure of the DR environment is always in a deployable state and notify you if there are any errors.
   1. Click on the CI/CD button in the topbar, it will open the CI/CD designer where you can create a new workflow

      <figure><img src="/files/QtOXni9jVKtc0ssFhkPS" alt=""><figcaption></figcaption></figure>
   2. Schedule the workflow to run on a regular basis:
      1. Click on the wheel button next to the name of the workflow to open its configuration.
      2. Enable the schedule by turning the switch on: Use crontab syntax for that. For example, if you want it to run every Monday at 6AM UTC time you put: `0 6 * * 1`
      3. Activate the notification to receive an email when the execution fails.

         <figure><img src="/files/0pEzZDkBwUaFbzmpSLkh" alt=""><figcaption></figcaption></figure>
      4. Add Terraform task and chose between, `plan` or `apply`. If you select \`apply\`, see the section below.

         <figure><img src="/files/i1PusyIKdWju2xtFLEoR" alt=""><figcaption></figcaption></figure>
5. **Full Deployability Test (FDT):** Brainboard allow you to automatically run a full deployability test, which means you can create a schedule to automatically deploy the DR environment completely and destroy it right after. This ensures that the DR environment is always in a deployable state.

   Here are the steps:

   1. Create a scheduled CI/CD workflow as described above. Don't forget to enable notifications in case any issue happens when the infrastructure is created or deleted.
   2. Add 2 Terraform tasks: one for `apply` and one for `destroy`.

      <figure><img src="/files/UPyMppaciSwhXybpqAYD" alt=""><figcaption></figcaption></figure>

      Once the workflow is triggered as specified in the schedule, it will create the infrastructure in the DR environment and if the deployment is successful, it will destroy it right after.

      If the deployment fails, you receive a notification.

{% hint style="info" %}
If you are planning to configure a Full Deployability Test, first, do an apply and check it that it is working properly before activating the schedule and automation.
{% endhint %}


# Cloud architectures


# Cloud resource ☁️

### Description

Cloud resource is any resource available at the cloud provider that has either a Terraform resource or data source associated with it.

* This resource can be drag & dropped from the left bar.
* Every cloud resource has a set of configuration parameters that you can customize in the Resource Configuration panel of that resource.
* There are **5** types of nodes:
  1. Cloud resource: this resource will be created when you provision the infrastructure.
  2. Data source: it refers to an existing cloud resource.
  3. Module: Terraform module.
  4. Container: it can contain other resource and give them its properties. E.g. AWS VPC, or Azure virtual network.
  5. Icon only: this resource is just graphic and has no Terraform representation.
* Refer to the [Resource Configuration](/cloud-design/right-panel/resource-configuration) page for more information on how to configure resources.

### Types of resources

Brainboard supports all the supported types by Terraform. You have the possibility to switch between the 2 types of resource from the switch in the left bar.

| Resource button                                 | Data sources button                                |
| ----------------------------------------------- | -------------------------------------------------- |
| ![resource button](/files/zwqQZymzZWyuRgRmreXy) | ![data source button](/files/p1OLlHng3P2aPxSvSXka) |

#### Resources

They represent resources available at the Terraform provider for a specific version.

#### Data sources

As per Terraform definition: Data sources allow Terraform to use information defined outside of Terraform, defined by another separate Terraform configuration, or modified by functions.

They are used in architecture to reference and/or get information about a resource already deployed. Data resources could be:

* A common resource shared between multiple architectures.
* For security reasons (read-only access) resources.
* Managed by another team.

**Agnostic nodes**

Nodes like Text, or generic icons have no cloud configuration and will not be deployed into the target cloud provider.

{% hint style="info" %}

* You can convert any cloud resource into an icon, so its code will be removed from the generated one.
  * You can put it back into cloud resource, its configuration will be preserved.
* You also have the possibility to hide the code of any cloud resource from the generated code by clicking on the hide icon in the Resource Configuration panel

  <figure><img src="/files/TWzwIdrOQS9z4y4PrY4h" alt=""><figcaption></figcaption></figure>
* You can change/customize the icon of any resource to reflect your preferences.
  {% endhint %}

### Supported cloud providers

Refer to the page [supported cloud providers](/data/cloud-providers/supported-cloud-providers) for more details.

### Interactions between nodes

When you drag-&-drop any resource, for any cloud provider, the Resource Configuration panel will open to allow you to configure its cloud parameters. Brainboard generates the Terraform code instantly when you close the panel.

There is a special type of resource called `containers`, which means you can drop resources inside them, Brainboard detects the relationship between them and automatically the added resource and populate the information in the right direction.

For example:

1. **AWS VPC & subnet**: when you add a subnet inside the VPC, Brainboard detects the relationship between them and automatically adds VPC information in the subnet resources.

   <figure><img src="/files/FM5nv5dtGr95UyMBItSo" alt=""><figcaption></figcaption></figure>
2. **Azure Virtual Network & subnet**: when you add a subnet inside a virtual network, Brainboard automatically detects their relationship and updates the code accordingly.

   <figure><img src="/files/qzzXdpUc5aGHJJTiU9Ad" alt=""><figcaption></figcaption></figure>
3. **GCP network & subnetwork**: when you have a subnetwork inside a network, Brainboard understands it and populates the inherited information automatically.

   <figure><img src="/files/Ey0BezkMDXY1vLZFpFZG" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Smart detection

* Brainboard detects which exported attribute is needed and automatically adds it to the resource. You don't need to do it automatically.
  * In the examples above, it detected that the `.id` is needed for AWS VPC and `.name` is needed for Azure vnet.
* Brainboard has the knowledge of the cloud provider of every resource and allows only actions allowed by the cloud provider.
  * E.g. you cannot add AWS resource inside an Azure container
* Within the same provider, Brainboard can understand what is allowed or not.
  * E.g. you cannot add a region inside a region, VPC inside a VPC, vnet inside vnet....
* When you change the `resource name` of any resource, Brainboard automatically updates all resources that reference it with the new value.
  {% endhint %}

#### Links between nodes aka Connectors

The connector links two components together and can exist in 2 forms:

1. **Automatically added**: this connector is added when you use a specific property of one node into the configuration of another one:

   <figure><img src="/files/tzFL2qc9s7RdhU2tPu05" alt=""><figcaption></figcaption></figure>

   In this example, Azure firewall uses in its public IP parameter the exported attribute `ID` of the resource public IP. Brainboard automatically generated this connect when the configuration is updated.
2. **Manually added**: This type of connector has no equivalent cloud configuration and it is just a graphical representation of the link that may exist outside of Terraform.

### Terraform code

When you add a resource into the design area, Brainboard generates its Terraform code instantly and automatically, and highlights it in the embedded VS Code editor.

When you click on any resource, Brainboard highlights it in the code and vice versa, when you click on the name of the resource in the code, Brainboard automatically selects the resource and opens its configuration menu.

### Best practices

* Always start by adding containers first into the design, this way Brainboard will detect automatically any resource you insert inside them, whatever the number of layers.
* If you want to stay compliant with Terraform, always put the Terraform resource name you choose as a text of the resource as well.
* Use the native auto-inheritance mechanism of Brainboard when you add resources. It saves you a lot of time.


# Terraform state file 🔐

### Description

Terraform stores the information of the execution (apply or destroy) in a special file called `tfstate`. This is file is critical for future provisioning of the infrastructure as it is the absolute reference of which resource has been deployed or not.

🛡️ Refer to the [remote backend page](/data/data-structure/cloud-architecture/remote-backend) for detailed information on how to configure and manage your state files in Brainboard.

### How it works

🎒 Refer to our [training session](https://youtu.be/Q3RYArLenYg) if you want to understand how Terraform works and how the tfstate is used.

![How Terraform works](/files/vqRkKb4yIfItSI2CqFZw)


# Graphics


# Values (Inputs & Outputs)

Variables are fundamental in every programming and scripting language because they are inherently useful in building dynamic programs. We use variables to store temporary values so that they can assist programming logic in simple as well as complex programs.

In Terraform, a variable is a way to store and reuse values throughout your Terraform code. Variables are defined using the `variable` block and can be used to parameterize your Terraform code, making it more flexible and reusable.

In terraform there are `4 types` of Variables that we separate in two main groups :

* Input variables
* Output variables

### Best practices

It is advisable to do the following when using input and output values:

1. **Use meaningful names**: Use descriptive and meaningful names for your input and output variables, so that it's clear what they represent. This makes it easier to understand the purpose of the variable and how it can be used.
2. Use input variables to **parameterize** your Terraform code: Use input variables to make your Terraform code more reusable and flexible. This allows you to use the same code in multiple environments or for different use cases.
3. **Validate input values**: Use the validation function to validate input values before Terraform applies the changes to the infrastructure, this will prevent errors and improve the reliability of your infrastructure.
4. Use output variables to **reference other resources**: Use output variables to reference other resources, this allows you to reference the value of other resources and use it across different parts of your infrastructure.
5. **Document** the usage of input and output variables: Document the usage of input and output variables so that others understand how it is used and what its intended usage is.


# Variables ⒳

### Definition

In Terraform, a variable is a way to store and reuse values throughout your Terraform code. Variables are defined using the `variable` block and can be used to parameterize your Terraform code, making it more flexible and reusable.

### Types

There are `three types` of variables in terraform that we can consider as input variables:

#### Local Variables

Local variables are a group of key-value pairs that can be used in the configuration. The values can be hard-coded or be a reference to another variable or resource. Local variables are accessible within the module/configuration where they are declared.

{% hint style="info" %}
Use local variables in combination with input variables: Use local variables with input variables. This allows you to use local values as input for other resources or modules, making your Terraform code more dynamic and reusable.
{% endhint %}

#### Input Variables

The purpose of input variables is to provide a way to parameterize a Terraform configuration. Input variables allow you to define values that can be passed into a Terraform configuration at runtime, rather than hard-coding them within the configuration itself. This makes your Terraform code more reusable and flexible, as it can be used in different environments or for different use cases with different input values.

#### Environment Variables

Environment variables can be used to configure various aspects of Terraform's behavior, such as the location of the state file or the API endpoint of the provider. Additionally, Terraform environment variables can be used to provide sensitive information, such as API keys or credentials, without storing them in plain text in the configuration files.

Here are a few examples of how Terraform environment variables can be used:

### Attributes

Here are attributes that you can set when creating a variable:

* **name**: the name of the variable
* **scope**: the level within which the variable will be used. Possible values are:
  * Organization
  * Architecture
  * Project
  * Environment
  * Local
* **type**: to identify the type of the variable being declared.
* **value**: the actual value of the variable. When you add this value, it will be put in the file `terraform.tfvars` to stay compliant with Terraform best practices.
* **default**: default value in case the value is not provided explicitly.
* **description**: describes the purpose of the variable.
* **validation**: rules to validate the input of the variable.
* **sensitive**: a boolean value. If true, Brainboard and Terraform will hide the variable’s value anywhere it is displayed.

Input variables support multiple data types. They are broadly categorized as simple and complex. `string`, `number`, `bool` are simple data types, whereas `list`, `map`, `tuple`, `object`, and set are complex data types.

### Create variables

To create a new variable:

1. Go to the input menu in the left bar

   ![add\_input\_variable](/files/pF5vlzKfZaXnWJ0KgoZ2)
2. Click on the + button next to the scope that you need to add the variable. It can be Organization, Project, Environment, Architecture and Locals

   ![add\_variable](/files/75fgL4WqwHlJ7R6Zi3br)
3. Add the needed information in the variable form

   ![Variable attributes](/files/I3ngwIOwCRs3G5w4Tqgs)
4. Click on the add button

### Edit variables

To edit a variable, follow the steps below:

![modify\_variables](/files/mukrvTKN29oT98ORvxW1)

### Delete variables

To delete a variable, just select the variable and click on the bin icon as below:

![delete\_variable](/files/GbpmSQWJUiKILSbl4WJf)

### Variable files

* The variables are kept in a file called `variables.tf`.
* The values of variables are kept in another file called `terraform.tfvars` to give you the possibility to have a different strategy for this file as it may contain sensitive information.


# Output 📺

### Definition

For situations where, e.g. you deploy a large web application infrastructure using Terraform, you often need certain endpoints, IP addresses, database user credentials, and so forth. This information is most useful for passing the values to modules, along with other scenarios.

`Output variables` in Terraform are used to display the required information in the console output after a successful application of configuration for the root module.

### Attributes

* **name**: the name of the output, which must be a valid identifier.
* **value**: an expression whose result is to be returned to the user.
* **description**: a description of the purpose of the output value.
* **sensitive**: a boolean value showing if terraform should hide the values in the messages from terraform plan and terraform apply.

### Scopes

Output values can be used for several purposes:

* To share data between Terraform modules: Output values can be used to pass data from one module to another, allowing you to share data between modules and keep your code organized.
* To export data for further usage: After creating a resource, you can output its ID, name, and other information that can be used to reference it later. This allows you to use the outputs in other parts of your infrastructure or in external systems.
* To debug your Terraform code: Output values can be used to debug your Terraform code. You can use it to output the values of certain variables or the status of certain resources, which can be helpful when troubleshooting issues.
* To make your Terraform code more reusable: By parameterizing your Terraform code with output values, you can make it more reusable and flexible. This allows you to use the same code in multiple environments or for different use cases.
* To access outputs after Terraform had been run: Output values can be stored in a state file, which allows you to access the outputs after Terraform has been run. This can be useful when you need to reference the resources created by Terraform later.
* To pass information to other parts of your infrastructure or to external systems: Output values can be used to pass information to other parts of your infrastructure or to external systems. This allows you to share data between different systems and automate the process of creating and managing infrastructure.

### Create output

To create an output, click on the output button on the left bar.

![outputs](/files/v4W5W5SgI8InA2thGMOT)

After you add the information, click on the check icon at the end of the row.

### Edit output

In cases when you want to modify an output, you can click on the pen on the right side. ![edit\_output](/files/F4ok0yPUlLvJ9lw5gSmg)

### Delete output

To delete an output, you need to click on the bin icon on the right side as below:

![delete\_output](/files/X84M1FyawMi6OpvSxicu)


# CI/CD engine

### Description

Brainboard CI/CD designer is a visual editor that allows you to build your pipelines without any YAML knowledge.

### Workflow

A workflow is a set of orchestrated stages that contain tasks which run either in parallel or sequentially.

So, it is a list of steps that you want your infrastructure to go through before, during and after the provisioning of your infrastructure.

![workflow](/files/6laY43Inbb76HBFN8DIF)

When you create a new architecture, Brainboard by default creates an empty workflow named `New workflow`.

#### Rename workflow

To rename a workflow, click on the wheel button on the right of the workflow name: ![Rename workflow](/files/BPHLfcsPNeOcfYLQGnAU)

### Task

Task, is an individual action that you want to run to do a specific job. E.g. Terraform apply, send Slack notification or update your ticketing system like ServiceNow.

Tasks can be created from the list of available plugins. Refer to the sections below to learn how to create tasks.

Refer to the [supported plugins](/automation/supported-plugins) page to see the options for each kind of task and how to configure it.

#### Task approval

Every task contains an approval option. When activated, the tasks will not be executed until approved by people or teams added in the approvers list.

This allows you to gate the execution of actions until explicitly approved by the right people or teams, and the approver has all the information needed to take a decision to approve the task or not.

When a task has an approval, it is called manual execution.

### Stage

A `stage` is a logical grouping of parallel tasks that will be executed at the same time. They are represented vertically in the CI/CD designer.

`Stages`, in the other hand, are horizontal and looks like columns. So there is an implicit dependency between them, which means that any given stage will not be executed until all tasks in the stage before complete successfully.

{% hint style="info" %}
You can `ignore errors` in tasks of a stage to not block the execution of following stages if it makes sense in your workflow.
{% endhint %}

#### Add a stage

As a stage is just a logical grouping of tasks, to add a new stage, click on the `plus` button on the right of any tasks

![Add stage](/files/zbzOgeNCrxWVycIFUg4K) ![Add stage after task](/files/rWJUM3E9H4bFA2uzH64a)

Then, add vertically the tasks you want to be executed `in parallel`.

#### Delete a stage

To delete a stage, you need to delete all its vertically stacked tasks.

### Create workflow template

When your workflow is complete and all information of tasks are filled, you can create a template from it to use it on any other architecture you have or you will create.

![Create workflow template](/files/huxMjH0NDqAhiEPQeIKL)

### Run pipeline

Once your workflow is configured, you can trigger the execution of the pipeline by clicking on the button `Run pipeline`.

![Run pipeline](/files/iDdduNyhz0DmSC4hxfeF)

When the pipeline is triggered, it switches to the `Pipelines` page where you can see the output of the execution in real time.

![Pipeline output](/files/XpOngHhXJrSA9PJd3qQQ)

Refer to the [pipelines page](/automation/pipelines) for detailed information about pipelines.

### Best practice

* It's always a good practice to introduce hygiene in the way you build the infrastructure by triggering pipelines to analyze your architecture before pushing into the git repository.
* Don't use generic email in task's approval unless the email is already a Brainboard user.


# Supported plugins

## Description

Plugins are open-source tools or software that are integrated in Brainboard and made available to use as part of your CI/CD pipelines.

These plugins are maintained and updated by Brainboard team, giving you always the latest releases available.

## All plugins

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Terraform</td><td><a href="/pages/ctry0dqqXfKopQnYBXhi">/pages/ctry0dqqXfKopQnYBXhi</a></td></tr><tr><td>TFsec</td><td><a href="/pages/jnlwcIQBDmfJFYzwLxWk">/pages/jnlwcIQBDmfJFYzwLxWk</a></td></tr><tr><td>Terrascan</td><td><a href="/pages/6dswQ8zzyWrkFKNFYsvl">/pages/6dswQ8zzyWrkFKNFYsvl</a></td></tr><tr><td>OPA</td><td><a href="/pages/quxzvQuVPJxNeUmh7f8r">/pages/quxzvQuVPJxNeUmh7f8r</a></td></tr><tr><td>Checkov</td><td><a href="/pages/uaLro6wIzLJuLovrvAZB">/pages/uaLro6wIzLJuLovrvAZB</a></td></tr><tr><td>Infracost</td><td><a href="/pages/fD9cRCKYtTxpesTPaEoa">/pages/fD9cRCKYtTxpesTPaEoa</a></td></tr><tr><td>Email</td><td><a href="/pages/yNxV193Hw3FoLCyOW0BJ">/pages/yNxV193Hw3FoLCyOW0BJ</a></td></tr><tr><td>Slack</td><td><a href="/pages/4j327zHhEbZE2FUbV1gO">/pages/4j327zHhEbZE2FUbV1gO</a></td></tr><tr><td>MS Teams</td><td><a href="/pages/voVTbV0GSWjvwzAKBDmm">/pages/voVTbV0GSWjvwzAKBDmm</a></td></tr><tr><td>Webhooks</td><td><a href="/pages/I9pCglhYMqzeNOkWXJrs">/pages/I9pCglhYMqzeNOkWXJrs</a></td></tr></tbody></table>

## Request a new integration

If you want to see your software integrated in Brainboard, you can request it or upvote for it in our [public roadmap](https://roadmap.brainboard.co).


# Terraform

This plugin allows you to execute <mark style="color:$primary;">**`Terraform`**</mark> actions on your code.

<figure><img src="/files/86MTr7TtWFIzLookIyYo" alt=""><figcaption></figcaption></figure>

### **Configuration options**

1. **Command:** Terraform commands to execute. Four options are available:
   * <mark style="color:$primary;">**`validate`**</mark>
   * <mark style="color:$primary;">**`plan`**</mark>
   * <mark style="color:$primary;">**`apply`**</mark>
   * <mark style="color:$primary;">**`destroy`**</mark>
2. **Version:** Refers to the Terraform binary version to use.
3. **Ignore failure:** if enabled, the next stage will execute even if the task fails.
4. **Target:** It is a **regex** to specify which resource(s) will be the target of the execution.\
   Refer to [this documentation page](https://developer.hashicorp.com/terraform/cli/commands/plan#resource-targeting) to understand how resource targeting works in Terraform
5. **Require approval:** means that this task will not be executed until approved by the people added to the approvers' list.

{% hint style="info" %}

* The task remains blocked until all approvers added to the list approve it.
* When enabled, it allows you to add approvers to the list.
  {% endhint %}

{% hint style="warning" %}
The approver has to be a Brainboard user.
{% endhint %}

### **Sample output**

![Terraform output](/files/vKu8lDafzdAmJJOQWgRF)


# Security


# Trivy

This plugin allows you to scan the Terraform code with <mark style="color:$primary;">**`trivy`**</mark> and provide output.

{% hint style="info" %} <mark style="color:$primary;">**`trivy`**</mark> is a static analysis security scanner that can be used for Terraform code.
{% endhint %}

* [Home page](https://trivy.dev/latest/docs/coverage/iac/terraform/)
* [Source code on GitHub](https://github.com/aquasecurity/trivy)

<figure><img src="/files/er92vgKmAHG7rHmf50xL" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **Name:** This is a <mark style="color:$primary;">**Brainboard**</mark> field to describe what this task is about.
2. **Ignore status:** List of vulnerability statuses to ignore:
   1. <mark style="color:$primary;">**`unknown`**</mark>
   2. <mark style="color:$primary;">**`not_affected`**</mark>
   3. <mark style="color:$primary;">**`affected`**</mark>
   4. <mark style="color:$primary;">**`fixed`**</mark>
   5. <mark style="color:$primary;">**`under_investigation`**</mark>
   6. <mark style="color:$primary;">**`will_not_fix`**</mark>
   7. <mark style="color:$primary;">**`fix_deferred`**</mark>
   8. <mark style="color:$primary;">**`end_of_life`**</mark>
3. **Scanners:** List of what security issues to detect:
   1. <mark style="color:$primary;">**`vuln`**</mark>
   2. <mark style="color:$primary;">**`misconfig`**</mark>
   3. <mark style="color:$primary;">**`secret`**</mark>
   4. <mark style="color:$primary;">**`license`**</mark>
4. **Severity:** Severities of security issues to be displayed:
   1. <mark style="color:$primary;">**`UNKNOWN`**</mark>
   2. <mark style="color:$primary;">**`LOW`**</mark>
   3. <mark style="color:$primary;">**`MEDIUM`**</mark>
   4. <mark style="color:$primary;">**`HIGH`**</mark>
   5. <mark style="color:$primary;">**`CRITICAL`**</mark>
5. **Ignore failure:** if enabled, the execution of the following stage will be triggered even if the task fails.
6. **Offline scan:** Do not issue API requests to identify dependencies
7. **Require approval:** It implies that this task will not be executed until approved by people added to the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.
8. **Config:** Can be used to pass any valid **Trivy** configuration page (see [documentation](https://trivy.dev/latest/docs/references/configuration/config-file/))
9. **Skip files:** Specify the files or glob patterns to skip.

**Sample output**

The output includes clickable links that open the relevant documentation pages listed in the <mark style="color:$primary;">**'More Information'**</mark> section.

<figure><img src="/files/FBeJgd7guNaf7FkH964j" alt=""><figcaption></figcaption></figure>


# Tfsec

This plugin allows you to scan the **Terraform** code with <mark style="color:$primary;">**`tfsec`**</mark> and provide output.

{% hint style="info" %} <mark style="color:$primary;">**`tfsec`**</mark> is a static analysis security scanner for your **Terraform** code.
{% endhint %}

* [Home page](https://aquasecurity.github.io/tfsec)
* [Source code on GitHub](https://github.com/aquasecurity/tfsec)

**Configuration options**

1. **Name:** This is a <mark style="color:$primary;">**Brainboard**</mark> field to describe what this task is about.
2. **Disable grouping:** Disable grouping of similar results.
3. **Ignore failure**: This will put the task in a non-blocking failure, which means the execution of the following stage will be triggered even if the task fails.
4. **Include ignored:** Include ignored checks in the result output.
5. **Include passed:** Include passed checks in the result output.
6. **Require approval:** It implies that this task will not be executed until approved by people added in the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.<br>
7. **Minimum severity:** You can specify the minimum severity of result that should be reported. By default, every severity is reported. You must use one of <mark style="color:$primary;">**`CRITICAL`**</mark><mark style="color:$primary;">**,**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**`HIGH`**</mark><mark style="color:$primary;">**,**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**`MEDIUM`**</mark><mark style="color:$primary;">**,**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**`LOW`**</mark>.
8. **Disabled checks:** comma-separated list of checks to exclude during the execution.
   1. This list has to be in this format: <mark style="color:$primary;">**`rule1,rule2,rule3...`**</mark>
   2. No space should be added after the comma in the list.

<figure><img src="/files/fo22n4q0FdL5qup7PxNG" alt=""><figcaption></figcaption></figure>

**Sample output**

The output includes clickable links that open the relevant documentation pages listed in the <mark style="color:$primary;">**'More Information'**</mark> section.

<figure><img src="/files/GxfSv0YTVZoeG0gjGThs" alt=""><figcaption></figcaption></figure>


# Terrascan

This plugin allows you to scan the Terraform code with <mark style="color:$primary;">**`Terrascan`**</mark> and provide output.

{% hint style="info" %} <mark style="color:$primary;">**`Terrascan`**</mark> is a static code analyzer for **Infrastructure as Code.**

It provides **500+ out**-of-the-box policies so that you can scan **IaC** against common policy standards such as the **CIS Benchmark.**
{% endhint %}

* [Home page](https://runterrascan.io/)
* [Source code on Github](https://github.com/tenable/terrascan)

<figure><img src="/files/BjNhJ3LuQQdEJEQ7mvgW" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **Name:** This is a <mark style="color:$primary;">**Brainboard**</mark> field to describe what this task is about.
2. **Scan rules:** Specify rules to scan, example: -**scan-rules**=<mark style="color:$primary;">**`“ruleID1,ruleID2”`**</mark>.
3. **Skip rules:** specify one or more rules to skip while scanning:
   1. Example: **–skip-rules**=<mark style="color:$primary;">**“ruleID1,ruleID2”**</mark>
   2. No space should be added after the comma in the list.
4. **Ignore failure:** this will put the task in a non-blocking failure, which means, the execution of the following stage will be triggered even if the task fails.
5. **Require approval:** It means that this task will not be executed until approved by people added to the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.
6. **Show passed:** Display passed rules, along with violations.

**Sample output**

<figure><img src="/files/4rZTN4KSlzPraJ8XptZo" alt=""><figcaption></figcaption></figure>


# OPA

This plugin allows you to check your Terraform code against security policies that you define.

`OPA` is a policy-based control for cloud native environments.

* [Home page](https://www.openpolicyagent.org/)
* [Source code on Github](https://github.com/open-policy-agent/opa)

<figure><img src="/files/47BNxKD6NUDMH7JQoOfL" alt=""><figcaption></figcaption></figure>

### **Configuration options**

1. Name: This is Brainboard field to describe what this task is about.
2. Policy: the content of your policy in `rego` format.
   1. The content in this output is just an example. See examples below.
3. Extra environment variables: variables that you can define here that will be used as environment variables in the execution shell.
4. Ignore failure: if enabled, the execution of the following stage will be triggered even if the task fails.
5. Require approval: means that this task will not be executed until approved by people added in the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list<br>

     <figure><img src="/files/WPdQEUM8EsHFyejNET0h" alt=""><figcaption></figcaption></figure>
   * The approver has to be Brainboard user
6. Decision: The decision you want the check to be evaluated against. In the format `package_name/decision`
   1. In this example, we want to fail the pipeline if the resources don't contain the tags in the list
   2. The decision is `brainboard/deny`

### **Sample output**

<figure><img src="/files/eDtvwXTbixeSL11UO7lv" alt=""><figcaption></figcaption></figure>

### Examples

#### Naming convention

<pre class="language-rego"><code class="lang-rego">package brainboard

deny contains msg if {
    r := input.resource_changes[_]
    r.type == "azurerm_storage_account"
    not startswith(r.change.after.name, "bb")
    
    msg := sprintf("%v must start with bb", [r.address])
}


deny contains msg if {
<strong>    r := input.resource_changes[_]
</strong>    r.type == "azurerm_resource_group"
    not startswith(r.change.after.name, "bb-")
    
    msg := sprintf("%v must start with bb-", [r.address])
}

</code></pre>

Decision: `brainboard/deny`

#### Mandatory tags

```rego
package brainboard

required_tags := ["Environment", "Owner"]

deny contains msg if {
	r := input.resource_changes[_]
	missing_tags := {tag | tag := required_tags[_]; not r.change.after.tags[tag]}

	msg = sprintf("Resource is missing required tags: %v (%v)", [r.address, missing_tags[_]])
}
```

Decision: `brainboard/deny`

#### Unrestricted ingress for AWS Security Group

```rego
package brainboard 

deny contains msg if {
  r := input.resource_changes[_]
  r.change.after.ingress[_].cidr_blocks[_] == "0.0.0.0/0"
  msg := sprintf("%v has 0.0.0.0/0 as allowed ingress", [r.address])
}
```

Decision: `brainboard/deny`


# Checkov

This plugin allows you to scan your **Terraform** code to find misconfigurations before they're deployed.

{% hint style="info" icon="link-horizontal" %}

* [Checkov home page](https://www.checkov.io/)
* [Source code on GitHub](https://github.com/bridgecrewio/checkov)
  {% endhint %}

### Accessing Checkov

1. Launch the **CI/CD Designer** by clicking the 🚀**CI/CD i**con available at the top.
2. Click <mark style="color:$primary;">**`+`**</mark> in the canvas to add a new task, and select <mark style="color:$primary;">**Checkov**</mark> from the available options. It will be added to the canvas, and its **Task details** slide form will appear on the right, where you can do the desired configuration.

<figure><img src="/files/H0fGu1nwcWb3FYSZwxQe" alt=""><figcaption></figcaption></figure>

### **Configuration options**

1. **Name:** This is the Brainboard field to describe what this task is about.
2. **Version:** Always points to the latest version to give you the latest security checks released.
3. **Skip checks.**
4. **Ignore failure:** This will put the task in a non-blocking failure, which means the execution of the following stage will be triggered even if the task fails.
5. **Require approval:** It implies that this task will not be executed until approved by the people added to the approvers' list.
   * The task remains blocked until all approvers added to the list approve it.
   * When enabled, it allows you to add approvers to the list.

{% hint style="warning" %}
The approver has to be a **Brainboard** user.
{% endhint %}

<figure><img src="/files/jRzlDS1effvzxyNiJAGX" alt="" width="488"><figcaption></figcaption></figure>

{% hint style="info" %}
**API key is optional.** If you have a paid subscription, you can add your key and repository ID.
{% endhint %}

**Sample output**

<figure><img src="/files/Y3cddgpFF1sWiNaLvH1v" alt=""><figcaption></figcaption></figure>


# Cost estimation


# Infracost

This plugin allows you to have a cost estimation for your infrastructure from your Terraform code.

* [Home page](https://www.infracost.io/).
* [Source code on Github](https://github.com/infracost/infracost).

<figure><img src="/files/lFc4I49D3MhxrprFyiMa" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **API key:** You can generate it from your Infracost account.
2. **Command:** 2 commands supported.
   * **Breakdown:** This command shows a cost breakdown.
   * **Diff:** This command shows a diff of monthly costs between the deployed infrastructure and planned changes.
3. **Disable cache**.
4. **Ignore failure:** If enabled, the execution of the following stage will be triggered even if the task fails.
5. **Require approval:** It means that this task will not be executed until approved by people added in the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.
6. **Show skipped:** List unsupported and free resources.
7. **Project name**

**Sample output**

![Infracost output](/files/8tZHBPBHJwCV9QeSlelP)


# Notifications


# Email

This plugin allows you to send an email to multiple recipients.

This is a <mark style="color:$primary;">**Brainboard**</mark> plugin.

<figure><img src="/files/sO0jUUQ3UpnBrKal0msx" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **Emails:** list of email addresses that will receive a copy of the message.
2. **Message:** **YAML** content to be emailed.
3. **Ignore failure:** if enabled, the execution of the following stage will be triggered even if the task fails.
4. **Require approval:** means that this task will not be executed until approved by people added to the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.


# Slack

This plugin allows you to send a notification to your **Slack** channel.

**Configuration options**

1. **Message:** content to be sent.
2. **URL** of your **Slack** incoming webhook.

<figure><img src="/files/C6u83OGydHTXha2hcfOv" alt=""><figcaption></figcaption></figure>

### Setup

1. **Create** a **Slack** application from scratch (<https://api.slack.com/apps>).
2. **Activate** incoming webhooks.
3. Create a **webhook** **URL** and copy this URL into the <mark style="color:$primary;">**Brainboard**</mark>**&#x20;Slack** plugin configuration

<figure><img src="/files/zJFlDYRnM1fJevpflJh0" alt=""><figcaption></figcaption></figure>


# Microsoft Teams

This plugin allows you to send a notification to your **MS Teams** channel.

<figure><img src="/files/vs0gozUTPoSGjPzEdgx2" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **Task name:** This name will be visible in the pipeline when the task is executed.
2. **Message:** Text to be sent.
3. **Title:** Title of the message that will be posted to the **Teams** channel.
4. **Webhook URL** of your **MS Teams** channel.
5. **Hide pipeline URL:** Do not add a button with a link to the pipeline in the adaptive card for the message displayed in the **Teams** channel.
6. **Ignore failure:** If enabled, the execution of the following stage will be triggered even if the task fails.
7. **Require approval:** It means that this task will not be executed until approved by people added in the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.

#### Setup instructions

If you want to configure **Microsoft Teams** to receive notifications from <mark style="color:$primary;">**Brainboard**</mark> pipelines, an ***incoming hook*** needs to be set up in the channel of your choice. To do so, follow the steps:

1. Go to your **Teams** channel where you want the notification to be posted, open its configuration menu in the top-right corner and click on **"**<mark style="color:$primary;">**Workflows**</mark>**."**<br>

   <figure><img src="/files/6xTw27vfQGYrzmntYYhD" alt=""><figcaption></figcaption></figure>

2. This will open the workflows configuration wizard. Search and select the line **"**<mark style="color:$primary;">**Post to a channel when a webhook request is received**</mark>**."**

<figure><img src="/files/1TGl55pxlxlipKBrbxNn" alt=""><figcaption></figcaption></figure>

3. Give it a name and click <mark style="color:$primary;">**`Next`**</mark>.

<figure><img src="/files/fzHcQFjANY6BB99bFm31" alt=""><figcaption></figcaption></figure>

4. Select the channel where you want the notification to be posted:

<figure><img src="/files/qO2D5BvSKJIghaljoZnN" alt=""><figcaption></figcaption></figure>

5. Copy the generated **webhook URL** to use in <mark style="color:$primary;">**Brainboard.**</mark>

<figure><img src="/files/UJ8dVKzd8r1BNLbzqjWs" alt=""><figcaption></figcaption></figure>

If you have an old configuration, follow the steps in this video:

{% embed url="<https://www.youtube.com/watch?v=LOvWCNyXxLE>" %}

{% hint style="warning" %}
This configuration is deprecated by **Azure** and will be removed by the end of 2025.
{% endhint %}


# Webhooks

This is a <mark style="color:$primary;">**Brainboard**</mark> plugin, and it allows you to communicate with an external system that is accessible through an **API.**

<figure><img src="/files/MzGL3Q70hB6X5GwSkRFp" alt=""><figcaption></figcaption></figure>

**Configuration options**

1. **URL** of the external system.
2. **Headers.**
3. **Ignore failure:** If enabled, the execution of the following stage will be triggered even if the task fails.
4. **Require approval:** It means that this task will not be executed until approved by people added to the approvers' list.
   * The task remains blocked until all approvers added in the list approve it.
   * When enabled, it allows you to add approvers to the list.
   * The approver has to be a <mark style="color:$primary;">**Brainboard**</mark> user.
5. **Message:** Payload to send with the API post request.
6. **Basic auth password.**
7. Method: <mark style="color:$primary;">**`GET`**</mark>, <mark style="color:$primary;">**`POST`**</mark>, <mark style="color:$primary;">**`PUT`**</mark>, **`PATCH`**, or <mark style="color:$primary;">**`DELETE`**</mark>.&#x20;
8. **Basic auth username.**


# Pipelines

### Description

Pipelines are the history of the execution of your workflow.

These pipelines contain both your triggered workflows and any action performed in <mark style="color:$primary;">**`one action`**</mark> tab.

![Pipeline overview](/files/AVy5vvTbnJ8oUHd56oqO)

### Pipeline information

<figure><img src="/files/W2wfTHISeNJ2egqC8EA4" alt=""><figcaption></figcaption></figure>

#### Status

There are 7 statuses of any given pipeline:

1. **Scheduled**: the pipeline is accepted by Brainboard for execution and put in the pool to be picked by a runner.
   * By default, all jobs are accepted.
2. **Pending**: the pipeline is pending to be picked by a runner to execute it.
3. **Running**: the pipeline has been picked by a runner that is currently executing its tasks.
4. **Succeeded**: the execution of the pipeline ended, and all tasks were successful.
5. **Failed**: the execution of the pipeline ended and some of the tasks failed.
   * The pipeline is considered failed, when at least one task fails.
   * When you ignore errors in tasks to not stop the pipeline, if they fail, the pipeline is considered failed even if the execution of the last task is successful.
6. **Terminated**: the pipeline has been stopped by a user.
7. **Manual**: the pipeline requires approval. It means that at least one task of the pipeline is pending approval.

<figure><img src="/files/7fKksOQZhdcZAKxw8HE2" alt=""><figcaption></figcaption></figure>

#### Unique identifier

Every pipeline has a unique identifier. It is used to store and retrieve its output.

The <mark style="color:$primary;">**`id`**</mark> displayed in this column is the last **12** characters of the **UUID** of the pipeline.

{% hint style="info" %}
The complete **UUID** is visible in the URL of the browser. You usually need it when you open a support ticket.
{% endhint %}

#### Visual stages and tasks

This is a minified graph of the pipeline.

It contains all tasks, and you can see the name and status of every task when you hover it.

#### Initiator

The avatar of the person who triggered the pipeline.

Hover this avatar to see the complete name of the person.

#### Date

Time when the pipeline was triggered.

#### Stop button

This button allows you to terminate/stop a running pipeline. It is only active when the pipeline is running.

### Run pipeline

To run the pipeline, go to the CI/CD designer and click on the button `Run pipeline`.

Refer to the [CI/CD page](/automation/ci-cd-designer) for more details.

### Stop pipeline

To stop the pipeline, click on the <mark style="color:red;">**`Stop pipeline`**</mark> icon located in the top right corner of the pipeline output window. This clickable icon is only active when the pipeline is running.

### Output

To open the output of any pipeline, click on it in the table of pipelines.

![Pipeline output](/files/XpOngHhXJrSA9PJd3qQQ)

#### Tasks status

Tasks have the same [status](#status) as the pipeline.


# Workflow templates

### Description

<mark style="color:$primary;">**`Workflow templates`**</mark> is a library of templates that contains all workflow scenarios that you build once and use everywhere.

{% hint style="warning" icon="lightbulb" %}
This is a great way to standardize your deployment process without reinventing the wheel, as it allows you to stay **DRY (don't repeat yourself)** even at the workflow level. You no longer need to copy and paste **YAML** files and manually change them for every architecture.
{% endhint %}

<figure><img src="/files/7curcuBTGmTVPGWsJXuX" alt=""><figcaption></figcaption></figure>

### Create template

To create a new template, refer to the page: [create workflow template](/automation/ci-cd-designer#create-workflow-template). It contains all the details.

### Clone template

To clone a template and add it to your architecture:

1. Go to the <mark style="color:$primary;">**`CI/CD`**</mark> tab in the top navigation bar, within your architecture.&#x20;
2. Click on <mark style="color:$primary;">**`Templates`**</mark> in the left menu.
3. Hover the workflow template you want to clone, and click on the **copy icon** at the bottom-right corner of the template thumbnail. Its tooltip will display <mark style="color:$primary;">**`Create workflow from template`**</mark> when hovered over.&#x20;
4. Confirm the action by clicking the <mark style="color:$primary;">**`Use template`**</mark> button on the <mark style="color:$primary;">**Create workflow from template**</mark> confirmation modal.&#x20;

<figure><img src="/files/0rrXiL7Peika0PME8wkp" alt=""><figcaption></figcaption></figure>

### Delete template

To delete a template:

1. Go to the <mark style="color:$primary;">**`CI/CD`**</mark> tab in the top navigation bar, within your architecture.&#x20;
2. Click on <mark style="color:$primary;">**`Templates`**</mark> in the left menu.
3. Hover the workflow template you want to clone, and click on the **bin icon** at the bottom-right corner of the template thumbnail. Its tooltip will display <mark style="color:$primary;">**`Delete template`**</mark> when hovered over.&#x20;
4. Confirm the action by clicking the <mark style="color:red;">**`Delete`**</mark> button on the <mark style="color:$primary;">**Workflow template deletion**</mark> confirmation modal.&#x20;

<figure><img src="/files/6oVLC7DKMvzlEnqgKw00" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Deleting a workflow template cannot be undone.
{% endhint %}

### Best practices

1. It's a good practice to include **security checks** as part of your process. Users will get used to it and will help you raise awareness about infrastructure security.
2. **Create** as **many workflows** as you can to represent your deployment scenarios. It helps your team members quickly pick the right one.
3. Always add a **description** when you create a template.
4. Put generic emails (the team's email) in the approvals field in tasks before creating templates so they are not dependent on specific persons.
5. You can use **naming conventions** for workflows, especially if you have workflows for different teams.


# Drift detection

### Overview

<mark style="color:$primary;">**Brainboard**</mark> allows you to detect any **drift** happening to the cloud infrastructure, and in some cases it removes the root cause of the drift.

### Detecting the drift

To detect a **drift** happening to the cloud infrastructure, you have **two** options. Both options are based on a workflow.

{% hint style="info" %} <mark style="color:$primary;">**Brainboard**</mark> is the only tool in the market that allows you to **create multiple CI/CD workflows** for the same infrastructure. You can, for e.g. create a workflow for security checks, another one for costs and a third one to detect a drift.
{% endhint %}

Refer to [this page](/automation/ci-cd-designer) if you want additional information about workflows.

#### Manual workflow

You can create a workflow to check if a drift has happened to the cloud infrastructure and run it manually as follows:

1. Go to the **CI/CD page** of the infrastructure by clicking on the **rightmost icon** in the options bar at the top.&#x20;
2. Either create a new workflow by clicking on the <mark style="color:$primary;">**`New workflow`**</mark> button or use the public template called <mark style="color:$primary;">**`[Public] Drift detection by Brainboard`**</mark>.

<figure><img src="/files/Dw6bzHiNyC7M8yvyUtmX" alt=""><figcaption></figcaption></figure>

3. Once the workflow is created, add a drift detection task and give it a name.

<figure><img src="/files/anvYXpqib8BJMIZEGoX6" alt=""><figcaption></figcaption></figure>

4. Run the pipeline by clicking the <mark style="color:$primary;">**`Run pipeline`**</mark> button in the top right corner of the page.&#x20;

<figure><img src="/files/9a1eytPo7dpnZvUi2W6l" alt=""><figcaption></figcaption></figure>

#### Scheduled automatic detection

1. Open the **settings** of the workflow you already created. To do so, click the **gear wheel** icon available next to the workflow name at the top of the page.&#x20;
2. Activate the cron **schedule** and specify the frequency of the execution of the workflow.
3. If you want to be notified when a drift is detected, enable <mark style="color:$primary;">**`Notify on failure`**</mark> and specify the email address(es) that will receive the notification.

<figure><img src="/files/BdEnD72BQQdnVMk6C3iP" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You can use this [crontab generator](https://codebeautify.org/crontab-format) to generate a cron expression.
{% endhint %}

### Output

When the pipeline runs (either manually or automatically), <mark style="color:$primary;">**Brainboard**</mark> creates an execution environment, runs the detection and gives you the output:

![Drift task output](/files/lIpsrmcMPfSnh1aHloQb)

{% hint style="info" %}
When a drift is detected, the workflow will be marked as <mark style="color:$primary;">**`failed`**</mark>, because when a drift happens, this is considered a failure by <mark style="color:$primary;">**Brainboard**</mark> as the infrastructure doesn't comply with the provisioned one.
{% endhint %}

### Best practices

It's a good practice to use the **automatic scheduled drift detection** for both:&#x20;

* **Critical workloads:** In case anything unwanted happens outside the source of truth.
* **Non-critical workloads:** To control costs and detect any modification that may increase them beyond the allowed budget.


# Types of drift

### Source of truth

The modern cloud infrastructure is more like a living organism than static resources that are not supposed to be updated frequently. That's why **IaC (Infrastructure as Code)** is the most suitable way to build and manage cloud infrastructure, whatever the language you pick. It could be **Terraform**, **Ansible, Pulumi, CloudFormation, Azure Bicep**...

This infrastructure is managed by different people, frequently introducing changes to it. That's why it is important to have <mark style="color:$primary;">**`a unique source of truth`**</mark>⁣. Otherwise, it will be challenging to track all the changes and troubleshoot errors/incidents when they occur.

By having a unique source of truth, it is also important to constantly monitor whether the real infrastructure (that is already provisioned in your cloud provider(s)) has not drifted from its source.

This source of truth could be <mark style="color:$primary;">**Brainboard**</mark>, **Git**, **local files**...

### Definition

A <mark style="color:$primary;">**drift**</mark> is when the actual state of the deployed infrastructure diverges from the desired or expected state described in the code. Usually, it occurs when changes are made directly/manually to the deployed infrastructure outside the **IaC** tool's control.

### Types of drift

There are two types of drift.&#x20;

#### **1. Between environments**

This happens when the deployed infrastructure in one environment for e.g. <mark style="color:$primary;">**`staging`**</mark> is different from another environment for e.g. <mark style="color:$primary;">**`production`**</mark> that is supposed to be part of the same lifecycle of the infrastructure.

**E.g.**

* When the dev environment is different from staging or QA or production.
* When the disaster recovery configuration is different from production.

<figure><img src="/files/uUiIpW5GZ9oQeFXyQQMm" alt=""><figcaption></figcaption></figure>

#### **2. Between the code and the infrastructure**

This happens when the provisioned cloud infrastructure (all resources and their configurations) is different from the configuration that you have in the source of the truth (**Terraform** code).

The **root cause** of the drift could be legitimate, e.g. when there is a security incident and as an emergency response, an engineer can choose to quickly do the action on the console of the cloud provider (like blocking a user) because it may take time to be done through **IaC** (especially if the infrastructure is big because **Terraform** may take hour(s) to refresh the state).

<figure><img src="/files/9tlrafzuu1rgHisOauzy" alt=""><figcaption></figcaption></figure>


# Remediation

### Definition

The <mark style="color:$primary;">**remediation**</mark> of a **drift** is the action of bringing back the deployed infrastructure and the code used to deploy it to the same state.

### Types of remediation

When a drift happens, you have **two** ways to remediate it:

#### 1. Override the infrastructure

This consists of redeploying the code that describes the infrastructure because it is the source of truth, and any changes happening outside the code should be reverted.

You have **two** methods to implement this type of remediation:

**I. Automatic**

In the drift detection workflow that you create, you can add **Terraform** apply as a task. This means whenever the workflow executes, it will always redeploy the current code when any change is detected.

<figure><img src="/files/KHdYxim03uDslHRORM0i" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To create a drift detection scheduled workflow, configure the **cron** via the **settings** (**gear icon** next to the workflow name)
{% endhint %}

{% hint style="danger" %}
This automatic remediation should be used with caution. It usually requires a team effort, and we advise you to always send a notification from any drift detection workflow you set up.
{% endhint %}

**II. Manual**

In this case, you manually inspect the output of the drift detection and manually redeploy the infrastructure, either by triggering the deployment pipeline or doing a Terraform apply from one action.

#### 2. Bring changes to the code

In this case, you add the changes that have been applied to provisioned infrastructure to the code.

This is useful and required in situations where the changes are legitimate. A common example is during a security incident and as an emergency response; users make the change on the cloud provider because it is quicker, especially if the pipeline to deploy with Terraform takes time.


# Self-Hosted Runner

{% hint style="warning" icon="info" %}
This feature is available in the **Enterprise Plan** only.
{% endhint %}

### Overview

<mark style="color:$primary;">**Brainboard**</mark>**&#x20;Runner** is a service that runs all **CI/CD** jobs in your organisation and sends the results back to <mark style="color:$primary;">**Brainboard**</mark>. A **self-hosted runner** allows you to run your pipeline jobs in your own infrastructure.

A self-hosted runner created is <mark style="color:blue;">**global**</mark> to your organization and will therefore process all jobs created within your organization, regardless of which project's architecture the jobs belong to, or which user created the job.

One organization can have multiple self-hosted runners, but these runners cannot be shared across multiple organizations.

{% hint style="success" %}
You can use **self-hosted runners** to run jobs in a **private network** or to customize the hardware and software configuration of the machines that run your jobs.
{% endhint %}

{% hint style="info" %} <mark style="color:$primary;">**Brainboard**</mark> self-hosted runner will need to be able to communicate with the <mark style="color:$primary;">**Brainboard**</mark>**&#x20;API** to get job information and send the results, so your network needs to allow outbound traffic to the Brainboard API in order for the runner to communicate with Brainboard.

However, you do not need any specific ingress rule, because the <mark style="color:$primary;">**Brainboard**</mark>**&#x20;API** does not communicate with the runner.
{% endhint %}

### Generate runner token

To use the **self-hosted runner**, you first have to generate a **runner token** from the <mark style="color:$primary;">**Brainboard**</mark> web application. To get the runner token, you have to be logged in with an account having organization's <mark style="color:$primary;">**`Admin`**</mark> or <mark style="color:$primary;">**`Owner`**</mark> permissions.

To generate the runner token:

1. Go to the [private self-hosted runner](https://app.brainboard.co/settings/integrations/private-selfhosted-runner?) settings page. On this page, you can create a new runner token or revoke an existing one.
2. Click on the <mark style="color:$primary;">**`New runner token`**</mark> button.
3. Click the <mark style="color:$primary;">**`Generate runner token`**</mark> button. &#x20;
4. **Copy** the generated token and save it for the deployment step.

<figure><img src="/files/lp5ieOybV3BWydgfdjFi" alt=""><figcaption></figcaption></figure>

### Deploy self-hosted runner

You can deploy the self-hosted runner in your environment using two methods:&#x20;

1. Docker-compose
2. Kubernetes

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td>Deploy runner with docker-compose [Easy]</td><td><a href="/pages/jLjZUKkB7NeygelZ7ssi">/pages/jLjZUKkB7NeygelZ7ssi</a></td><td><a href="/files/tAH4vdRdrhNgyDTsek4W">/files/tAH4vdRdrhNgyDTsek4W</a></td></tr><tr><td>Deploy runner with Kubernetes [Advanced]</td><td><a href="/pages/R6WeIcJNahRd96MFuFKa">/pages/R6WeIcJNahRd96MFuFKa</a></td><td><a href="/files/LdluumKjPm0cR1eJfhCI">/files/LdluumKjPm0cR1eJfhCI</a></td></tr></tbody></table>


# Deploy runner with Docker-Compose

### Pre-requisites

First, you need to have **Docker** installed on your server. If not already installed, please follow the instructions on [this page](https://docs.docker.com/engine/install/).

After installing **Docker**, you need the following files in a directory:

{% code title="docker-compose.yml" fullWidth="false" %}

```yaml
services:
  runner:
    image: ghcr.io/brainboard/runner:latest
    # You can also pin the version using any Brainboard version from our changelog (https://docs.brainboard.co/changelog)
    # image: ghcr.io/brainboard/runner:2026.06.9
    restart: unless-stopped
    command: [ "/brainboard-runner" ]
    stop_grace_period: 240s
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "./runner-config.yaml:/etc/brainboard-runner/config.yaml:ro"
      - "/tmp:/tmp"
```

{% endcode %}

{% code title="runner-config.yaml" fullWidth="false" %}

```yml
log: 
  level: warn

runner:
  name: "self-hosted runner"
  token: "your-runner-token"

# API Base url (default to https://api.us1.brainboard.co)
# api:
#  endpoint: "https://api.apac1.brainboard.co"
```

{% endcode %}

<details>

<summary>Full configuration example</summary>

#### Configuration

<table><thead><tr><th width="173.66668701171875">Key</th><th width="100.0001220703125">Section</th><th width="105.999755859375">Required</th><th width="86.666748046875">Type</th><th width="128">Possible Values</th><th>Default</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong><code>log.level</code></strong></mark></td><td><strong><code>log</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><mark style="color:blue;"><strong><code>trace</code></strong></mark>, <mark style="color:blue;"><strong><code>debug</code></strong></mark>, <mark style="color:blue;"><strong><code>info</code></strong></mark>, <mark style="color:orange;"><strong><code>warn</code></strong></mark>, <mark style="color:red;"><strong><code>error</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>info</code></strong></mark></td></tr><tr><td><sub><mark style="color:$primary;"><strong><code>log.format</code></strong></mark></sub></td><td><strong><code>log</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><mark style="color:blue;"><strong><code>json</code></strong></mark>, <mark style="color:blue;"><strong><code>pretty</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>json</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.name</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub><mark style="color:red;"><strong>Required</strong></mark></sub></td><td><sub>string</sub></td><td>any string</td><td>—</td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.token</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub><mark style="color:red;"><strong>Required</strong></mark></sub></td><td><sub>string</sub></td><td>any string</td><td><mark style="color:$primary;"><strong><code>$RUNNER_TOKEN</code></strong></mark> env var</td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.concurrency</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub>Optional</sub></td><td><sub>integer</sub></td><td><mark style="color:blue;"><strong><code>1</code></strong><strong>–</strong><strong><code>255</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>4</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.temporary_dir</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><sub>any path</sub></td><td><mark style="color:$primary;"><strong><code>$RUNNER_TEMP_DIR</code></strong></mark> or <mark style="color:$primary;"><strong><code>/tmp/brainboard-runner</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.poll_interval</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub>Optional</sub></td><td><sub>duration</sub></td><td>e.g. <mark style="color:blue;"><strong><code>10s</code></strong></mark>, <mark style="color:blue;"><strong><code>1m</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>10s</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.max_job_wait_time</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub>Optional</sub></td><td><sub>duration</sub></td><td>e.g. <mark style="color:blue;"><strong><code>1s</code></strong></mark>, <mark style="color:blue;"><strong><code>500ms</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>1s</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>runner.job_max_execution_time</code></strong></mark></td><td><strong><code>runner</code></strong></td><td><sub>Optional</sub></td><td><sub>duration</sub></td><td>e.g. <mark style="color:blue;"><strong><code>240m</code></strong></mark>, <mark style="color:blue;"><strong><code>4h</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>240m</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>api.endpoint</code></strong></mark></td><td><strong><code>api</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><sub>any URL</sub></td><td><mark style="color:$primary;"><strong><code>https://api.us1.brainboard.co</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>api.http_timeout</code></strong></mark></td><td><strong><code>api</code></strong></td><td><sub>Optional</sub></td><td><sub>duration</sub></td><td>e.g. <mark style="color:blue;"><strong><code>30s</code></strong></mark>, <mark style="color:blue;"><strong><code>2m</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>60s</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>executor.docker.worker_image</code></strong></mark></td><td><strong><code>executor</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><sub>any <strong>Docker</strong> image reference</sub></td><td><mark style="color:$primary;"><strong><code>ghcr.io/brainboard/plugins/worker:latest</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>executor.docker.ecr_region</code></strong></mark></td><td><strong><code>executor</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><sub>any <strong>AWS</strong> region</sub></td><td><mark style="color:$primary;"><strong><code>$AWS_REGION</code></strong></mark> env var or <mark style="color:$primary;"><strong><code>us-east-1</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>metrics.enabled</code></strong></mark></td><td><strong><code>metrics</code></strong></td><td><sub>Optional</sub></td><td><sub>boolean</sub></td><td><mark style="color:blue;"><strong><code>true</code></strong></mark>, <mark style="color:red;"><strong><code>false</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>true</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>metrics.hostname</code></strong></mark></td><td><strong><code>metrics</code></strong></td><td><sub>Optional</sub></td><td><sub>string</sub></td><td><sub>any bind address</sub></td><td><mark style="color:$primary;"><strong><code>0.0.0.0</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong><code>metrics.port</code></strong></mark></td><td><strong><code>metrics</code></strong></td><td><sub>Optional</sub></td><td><sub>integer</sub></td><td><mark style="color:blue;"><strong><code>1</code></strong><strong>–</strong><strong><code>65535</code></strong></mark></td><td><mark style="color:$primary;"><strong><code>9090</code></strong></mark></td></tr></tbody></table>

* <mark style="color:red;">\*</mark>**runner.token** must be provided either in the config file or via the <mark style="color:blue;">**`RUNNER_TOKEN`**</mark> environment variable.
* Duration fields accept suffixes: <mark style="color:blue;">**`ms`**</mark><mark style="color:blue;">**,**</mark><mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**`s`**</mark><mark style="color:blue;">**,**</mark><mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**`m`**</mark><mark style="color:blue;">**,**</mark><mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**`h`**</mark><mark style="color:blue;">**,**</mark><mark style="color:blue;">**&#x20;**</mark><mark style="color:blue;">**`d`**</mark> (e.g. **`500ms`, `30s`, `5m`, `2h`, `1d`**).

#### Full example of runner-config.yaml

{% code title="runner-config.yaml" %}

```yaml
log:
  level: debug
  format: json          # optional: json (default) or pretty

runner:
  name: "my-runner"
  token: "my-token"
  concurrency: 4
  poll_interval: 20s
  max_job_wait_time: 1s
  job_max_execution_time: 240m
  temporary_dir: "/tmp/brainboard-runner"

api:
  endpoint: "https://api.us1.brainboard.co"
  http_timeout: 60s

executor:
  docker:
    worker_image: "ghcr.io/brainboard/plugins/worker:latest"
```

{% endcode %}

</details>

<details>

<summary>Runner migration (&#x3C; 2026.06.7)</summary>

1. In <mark style="color:blue;">**`docker-compose.yml`**</mark>, update both the image tag and command:

```diff
-    image: ghcr.io/brainboard/runner:2026.02.3
+    image: ghcr.io/brainboard/runner:latest # or 2026.06.9
     restart: unless-stopped
-    command: /brainboard-runner run
+    command: /brainboard-runner
```

2. Replace your <mark style="color:blue;">**`runner-config.yaml`**</mark> with the one above; here are the required updates:

Notable changes for <mark style="color:blue;">**`runner-config.yaml`**</mark>:

* **Duration format**: All duration fields (<mark style="color:$primary;">**`poll_interval`**</mark>, <mark style="color:$primary;">**`http_timeout`**</mark>, <mark style="color:$primary;">**`max_job_wait_time`**</mark>, <mark style="color:$primary;">**`job_max_execution_time`**</mark>) now require an explicit unit suffix (e.g. <mark style="color:$primary;">**`20s`**</mark><mark style="color:$primary;">**,**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**`60s`**</mark><mark style="color:$primary;">**,**</mark><mark style="color:$primary;">**&#x20;**</mark><mark style="color:$primary;">**`240m`**</mark>). Raw integers are not accepted.
* **ECR authentication**: The <mark style="color:$primary;">**`ecr_auth`**</mark> flag is removed. ECR credentials are fetched automatically whenever the <mark style="color:$primary;">**`worker_image`**</mark> URL points to an ECR registry (hostname ending in <mark style="color:blue;">**`.dkr.ecr.*.amazonaws.com`**</mark>).
* **Log level override**: The <mark style="color:blue;">**`--level`**</mark> / <mark style="color:blue;">**`-l`**</mark> CLI flag and the <mark style="color:blue;">**`LOG_LEVEL`**</mark> environment variable still override <mark style="color:blue;">**`log.level`**</mark> at startup.

```diff
-level: warn
+log:
+  level: warn

 runner:
-  poll_interval: 5
+  poll_interval: 5s
```

3. Then restart your runner: <mark style="color:blue;">**`docker compose up -d`**</mark> / <mark style="color:blue;">**`docker compose up -d --force-recreate`**</mark>

</details>

### Configuration

The <mark style="color:blue;">**`runner-config.yaml`**</mark> file contains the <mark style="color:$primary;">**Brainboard**</mark> runner configuration. You can modify this file to change the runner's configuration. It's important to note that the <mark style="color:blue;">**`runner-config.yaml`**</mark> file should be in the same directory as the <mark style="color:blue;">**`docker-compose.yml`**</mark> file.

Before starting the runner for the first time, it is mandatory to update the <mark style="color:blue;">**`runner.token`**</mark> configuration value in the <mark style="color:blue;">**`runner-config.yaml`**</mark> file. Update this value with the private self-hosted runner token you generated from the <mark style="color:$primary;">**Brainboard**</mark> settings page.

```yaml
runner:
  token: "your-runner-token"
```

This token should be unique and <mark style="color:red;">**cannot**</mark> be shared **across multiple runners**. If you use the same token on multiple runners, you will encounter issues when running **CI/CD** jobs.

### Starting the runner

To start the runner, open a terminal and navigate to the directory where you downloaded the docker-compose and runner-config files. The following command will start the runner in the background:

```bash
docker compose up -d
```

Then, you can check on <mark style="color:$primary;">**Brainboard's**</mark> dashboard the last heartbeat and the status.

### Usage

If you want to see the logs, you can run this command:

```bash
docker compose logs -f
```

To stop the <mark style="color:$primary;">**Brainboard**</mark> runner, execute the following command:

```bash
docker compose down
```


# Deploy runner with Kubernetes

{% hint style="warning" icon="info" %}
**Feature Availability: Self-Hosted Runner** is available in the **Enterprise Plan** only.
{% endhint %}

### Pre-requisites

* A running **Kubernetes cluster**
* [Helm](https://helm.sh/docs/intro/install) installed locally
* **Kubectl** installed locally

<mark style="color:$primary;">**Brainboard**</mark> provides a **Helm** chart to deploy the runner in your existing **Kubernetes cluster.**

{% hint style="info" %}
Please contact support to get your customer token (<mark style="color:blue;">**`CUSTOMER_TOKEN`**</mark>) to access the charts.
{% endhint %}

```shell
helm registry login ghcr.io --username brainboard --password $CUSTOMER_TOKEN
```

To see the charts values and documentation, you can use the following commands:

```bash
helm show values oci://ghcr.io/brainboard/helm/brainboard-runner
helm show readme oci://ghcr.io/brainboard/helm/brainboard-runner
```

### Installation

For the runner to enrol with your organization, you will need to provide the **private self-hosted runner** token you generated from the <mark style="color:$primary;">**Brainboard**</mark> settings page.

You can install the runner with the following command:

```bash
helm install runner oci://ghcr.io/brainboard/helm/brainboard-runner --set config.credentials.token="your-runner-token"
```

{% hint style="success" %}
You can **view** all available configuration options using the commands above.
{% endhint %}

### Usage

To **open a terminal** inside the runner container, use the following command:

```bash
POD_NAME=$(kubectl get po -l app.kubernetes.io/name=brainboard-runner -o=name)
kubectl exec -ti ${POD_NAME} -c runner -- sh
```

If you want to see the logs, you can run this command:

```bash
kubectl logs -l app.kubernetes.io/name=brainboard-runner -c runner
```


# API


# Overview

## Settings

**Settings** in <mark style="color:$primary;">**Brainboard**</mark> provide a flexible and hierarchical configuration system allowing you to manage settings at different levels of your organization.

### Overview

Settings in <mark style="color:$primary;">**Brainboard**</mark> are organized in a hierarchical structure that follows this inheritance pattern.

{% hint style="info" icon="sitemap" %}
**Organization → Project → Environment → Architecture**
{% endhint %}

{% hint style="success" %}
This hierarchical approach ensures that configurations that are shared across the hierarchy can be managed efficiently while allowing for specific overrides at any level when needed.
{% endhint %}

### Accessing Settings

#### Organization Settings

To access the **Organization's settings,** go to the <mark style="color:$primary;">**`Settings`**</mark> option in the **left bar** and then click <mark style="color:$primary;">**`Organization`**</mark>**.** &#x20;

<figure><img src="/files/GKsQGFttWGvw6izybdH6" alt=""><figcaption></figcaption></figure>

#### Project Settings

To access the **Project's settings,** go to the <mark style="color:$primary;">**`Settings`**</mark> option in the **left bar** and then click <mark style="color:$primary;">**`Projects`**</mark>**.** Then, click the **ellipsis** (three dots) against the project name and click <mark style="color:$primary;">**`Change Settings`**</mark> in the dropdown menu. It will navigate you to the project's settings page.&#x20;

<figure><img src="/files/SkCQJ0fjVd7ZCnoLSpxG" alt=""><figcaption></figcaption></figure>

#### Environment Settings

Once you are on the <mark style="color:$primary;">**Project settings**</mark> page, you can also view the associated environments at the top. Click on the desired environment to go to its settings page.&#x20;

<figure><img src="/files/AtjUMr0u6CMYdtCgGvHy" alt=""><figcaption></figcaption></figure>

#### Architecture Settings

1. Open your architecture.
2. Switch to the **settings** **tab** using the **settings icon** in the options bar at the top.&#x20;

<figure><img src="/files/ur28INqCvVRrB8rbFGGV" alt=""><figcaption></figcaption></figure>

### Hierarchical Settings Management

#### Inheritance chain

Settings follow a clear inheritance structure:

1. **Organization Level**: The highest level, affects all projects, environments, and architectures.<br>

<figure><img src="/files/evYS2Kgx1Nf8KOYK6b00" alt=""><figcaption><p>Settings defined at organization level and not overridden at any lower level</p></figcaption></figure>

2. **Project Level**: Overrides organization settings for all environments and architectures within the project

<figure><img src="/files/ALiFS1DfJtrVTygPkEki" alt=""><figcaption><p>Setting defined at organization level being overridden at a project level</p></figcaption></figure>

3. **Environment Level**: Overrides organization and project settings for all architectures within the environment

<figure><img src="/files/nmcIp27G05fm6lL1lyNq" alt=""><figcaption><p>Setting defined at organization level being overridden at a project level and again at an environment level</p></figcaption></figure>

4. **Architecture Level**: The most specific level, overrides all higher-level settings for a particular architecture

<figure><img src="/files/nbqqQETbUXNhW8njb8SW" alt=""><figcaption><p>Setting defined at organization level being overridden at a project level , then overridden again at an environment level and finally at the architecture level</p></figcaption></figure>

#### Visual Indicators

When viewing settings at any level, you'll see visual indicators showing:

1. When a setting is locked at a higher level (with the source of the lock).

<figure><img src="/files/pkilQ8pjgpFeceqeKJmB" alt="" width="272"><figcaption></figcaption></figure>

2. When a setting is overridden at your level (the reset button shows that the value is set at this level).

<p align="center"><img src="/files/6J5vnmOQZhc7QMH6nmjq" alt=""></p>

3. When a setting is locked at your level, preventing any lower levels from updating.<br>

<figure><img src="/files/CEKpLtGBSIbo8mRe2aHY" alt="" width="298"><figcaption></figcaption></figure>


# Authentication

### Description

In this section you have all information you need to authenticate to Brainboard and allowing your users to sign in whether you are using SSO or just with email and password.


# Login into Brainboard

### Links

To start using <mark style="color:$primary;">**Brainboard**</mark>, you have either to:

1. Log in on [this](https://app.brainboard.co/login) page.
2. Go to [this](https://app.brainboard.co/register) page, then click on <mark style="color:$primary;">**`register`**</mark>.

### Sign-in options

Brainboard provides the following sign-in options:

* **Email and password:** Enter your email address and provide a password.
* [Single sign on (SS0)](/settings/authentication/sso)
* Sign in with **Google** and Microsoft: you can use Google or Microsoft to connect to <mark style="color:$primary;">**Brainboard**</mark>. You need to log in to these platforms first.


# Single sign-on (SSO)

### Introduction

{% hint style="warning" icon="info" %}
This feature is available only in the <mark style="color:$primary;">**`Enterprise`**</mark> plan and must be configured with the support team.
{% endhint %}

<mark style="color:$primary;">**Brainboard**</mark> offers **SAML** integrations to **Enterprise** accounts so that admins can easily manage users' access via their **IDP.**

{% hint style="success" %}
At <mark style="color:$primary;">**Brainboard**</mark>, we support both <mark style="color:blue;">**`SAML 2`**</mark> (recommended) & <mark style="color:blue;">**`OIDC`**</mark>.
{% endhint %}

<mark style="color:$primary;">**Brainboard's**</mark>**&#x20;SAML** integration allows you to connect <mark style="color:$primary;">**Brainboard**</mark> to your **IDP** so all users in your <mark style="color:$primary;">**Brainboard**</mark> organization can quickly and securely authenticate through your **IDP** using **SSO**. New users will automatically be created in <mark style="color:$primary;">**Brainboard**</mark> when they sign in for the first time after being allowed in your **IDP.**

Once **SSO** is enabled for your organization, you will have your own tenant at <mark style="color:$primary;">**Brainboard**</mark> with a dedicated **URL** with the following format: <mark style="color:blue;">**`https://xxx.app.brainboard.co`**</mark>

### Setup

#### 1. Tenant information

To get your tenant, you must reach out to the support team.

It might be shared by the <mark style="color:$primary;">**Brainboard**</mark> team via email before the first onboarding session.

#### 2. Set up SAML or OIDC in your IDP

{% tabs %}
{% tab title="SAML" %}
**SAML 2.0** standard is supported.&#x20;

Information needed to configure the SAML connection in your IDP:

| Identifier (Entity ID)                                       | <https://auth.brainboard.co/realms/{TENANT}>                                                           |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| <mark style="color:$primary;">**Reply/Assertion URL**</mark> | <mark style="color:blue;">**`https://auth.brainboard.co/realms/{TENANT}/broker/saml/endpoint`**</mark> |
| <mark style="color:$primary;">**Sign on URL**</mark>         | <mark style="color:blue;">**`https://{TENANT}.app.brainboard.co`**</mark>                              |
| {% endtab %}                                                 |                                                                                                        |

{% tab title="OIDC" %}

1. During the app creation, you need to allow the following redirect\_uri: <mark style="color:blue;">**`https://auth.brainboard.co/realms/{TENANT}/broker/microsoft/endpoint`**</mark>
2. Then please share the following information:
   * Tenant ID
   * Application ID
   * Secret value (You can use [https://privatebin.brainboard.co](https://privatebin.brainboard.co/) and send our team the link after)

If you need any help, reach out to our team.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Do not forget to replace <mark style="color:blue;">**`{TENANT}`**</mark> with your tenant shared by the team.
{% endhint %}

<mark style="color:$primary;">**Brainboard**</mark> will automatically configure the following mappers **(Azure Entra ID standard)**:

<table><thead><tr><th width="164.4921875">User attribute</th><th width="109.1146240234375">Required</th><th width="599.6875">Attribute Name</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong>email</strong></mark></td><td>Required</td><td><mark style="color:blue;"><strong><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong>firstname</strong></mark></td><td>Required</td><td><mark style="color:blue;"><strong><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong>lastname</strong></mark></td><td>Required</td><td><mark style="color:blue;"><strong><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong>groups</strong></mark> <sub>(see below)</sub></td><td>Optional</td><td><mark style="color:blue;"><strong><code>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</code></strong></mark></td></tr><tr><td><mark style="color:$primary;"><strong>organization_role</strong></mark></td><td>Optional</td><td><mark style="color:blue;"><strong><code>organization_role</code></strong></mark></td></tr></tbody></table>

#### 3. Automatic team provisioning and association from IDP Groups \[Optional]

Brainboard supports automatic team provisioning and association.

Every time users log in, they will be assigned to their respective team using the IDP Groups. The team will be created if it doesn't exist yet.

**Azure Entra ID**

1. In **Azure Entra ID,** open the <mark style="color:blue;">**`Enterprise Application`**</mark> - <mark style="color:blue;">**`Single sign-on`**</mark>
2. Edit the <mark style="color:blue;">**`Attributes & Claims`**</mark>
3. Add a <mark style="color:blue;">**`Group claims`**</mark> with the following configuration:

* Groups assigned to the application
  * **Source attribute:** cloud-only group display names\
    (or any option to share a friendly name to <mark style="color:$primary;">**Brainboard**</mark> — this attribute will be used for **Teams**' names)

<div data-with-frame="true"><figure><img src="/files/fnyZZFLAU8q7t8d6luzJ" alt=""><figcaption><p>Azure Entra ID - Group claims</p></figcaption></figure></div>

**Okta IDP**

For **Okta**, you need to set up the **Group Attribute Statements** like this:

<div data-with-frame="true"><figure><img src="/files/lKyhcz5rpW1rQrtWQz8H" alt="Okta IDP - Group Attribute Statements"><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you have a specific provider, please reach out to our support team to help you configure it.
{% endhint %}

#### 4. Share your IDP metadata

To finalize the configuration, you must share your **IDP metadata** (<mark style="color:blue;">**URL**</mark> or <mark style="color:blue;">**XML**</mark> file) with the <mark style="color:$primary;">**Brainboard**</mark> support team.

The team will get back to you to confirm your new tenant URL and run a few tests if needed.




---

[Next Page](/llms-full.txt/1)