# Bluebricks Help Center

<h2 align="center">How can we help you?</h2>

<p align="center"><button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask a question...</button></p>

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Guides, concepts, and CLI reference</td><td><a href="https://docs.bluebricks.co">https://docs.bluebricks.co</a></td></tr><tr><td><strong>Changelog</strong></td><td>See what's new in Bluebricks</td><td><a href="https://docs.bluebricks.co/bluebricks-documentation/changelog">https://docs.bluebricks.co/bluebricks-documentation/changelog</a></td></tr><tr><td><strong>Contact Support</strong></td><td>Get help from the team</td><td><a href="https://www.bluebricks.co/support">https://www.bluebricks.co/support</a></td></tr></tbody></table>

#### Browse by topic

<details>

<summary><strong>Authentication</strong><br>Login issues, expired tokens, and API keys</summary>

[Login fails or times out](/docs/help/troubleshooting/authentication.md#bricks-login-fails-or-times-out)

[Token expired errors](/docs/help/troubleshooting/authentication.md#token-expired-errors)

[Authentication priority order](/docs/help/troubleshooting/authentication.md#authentication-priority-order)

["Login was denied" error](/docs/help/troubleshooting/authentication.md#login-was-denied-error)

[API key rejected](/docs/help/troubleshooting/authentication.md#api-key-rejected)

[Not assigned to collection](/docs/help/troubleshooting/authentication.md#not-assigned-to-collection)

</details>

<details>

<summary><strong>Deployments &#x26; runs</strong><br>Stuck runs, approval blocks, environment errors, and slug conflicts</summary>

[Run stuck in planning or installing](/docs/help/troubleshooting/deployments.md#run-stuck-in-planning-or-installing)

[Approve & Apply button disabled](/docs/help/troubleshooting/deployments.md#approve-and-apply-button-disabled)

[Cost quota exceeded](/docs/help/troubleshooting/deployments.md#cost-quota-exceeded)

[Failed to acquire lock](/docs/help/troubleshooting/deployments.md#failed-to-acquire-lock)

[Plan shows unexpected changes](/docs/help/troubleshooting/deployments.md#plan-shows-unexpected-changes)

[Environment or deployment not found](/docs/help/troubleshooting/deployments.md#environment-or-deployment-not-found)

[Run already in progress](/docs/help/troubleshooting/deployments.md#run-already-in-progress)

[Environment slug conflicts](/docs/help/troubleshooting/deployments.md#environment-slug-conflicts)

</details>

<details>

<summary><strong>Packages &#x26; blueprints</strong><br>Publishing errors, invalid references, and validation failures</summary>

[Invalid bricks.json](https://bluebricks.co/docs/help/pages/T7O1LndmFeCS1x2Yhhxk#invalid-bricks.json)

[Blueprint output reference errors](/docs/help/troubleshooting/packages.md#blueprint-output-reference-errors)

[Invalid property or output names](/docs/help/troubleshooting/packages.md#invalid-property-or-output-names)

[Package not found](/docs/help/troubleshooting/packages.md#package-not-found)

[Publish failed](/docs/help/troubleshooting/packages.md#publish-failed)

[Artifact cannot be deployed](/docs/help/troubleshooting/packages.md#artifact-cannot-be-deployed)

[Package version disabled](/docs/help/troubleshooting/packages.md#package-version-disabled-or-not-enabled)

[Missing required secrets](/docs/help/troubleshooting/packages.md#missing-required-secrets)

</details>

<details>

<summary><strong>Cloud connections</strong><br>AWS, Azure, GCP, and self-hosted connection problems</summary>

[Collection missing cloud account](/docs/help/troubleshooting/cloud-connections.md#collection-missing-cloud-account)

[AWS role assumption fails](/docs/help/troubleshooting/cloud-connections.md#aws-role-assumption-fails)

[GCP authentication error](/docs/help/troubleshooting/cloud-connections.md#gcp-authentication-error)

[Self-hosted runner unreachable](/docs/help/troubleshooting/cloud-connections.md#self-hosted-runner-unreachable)

[Collection locked](/docs/help/troubleshooting/cloud-connections.md#collection-locked)

</details>

<details>

<summary><strong>Self-hosted runner</strong><br>OOMKilled jobs, stuck tasks, storage and Helm issues</summary>

[Runner pods OOMKilled](/docs/help/troubleshooting/self-hosted-runner.md#runner-pods-oomkilled)

[Tasks stuck in pending](/docs/help/troubleshooting/self-hosted-runner.md#tasks-stuck-in-pending)

[Auth errors in runner logs](/docs/help/troubleshooting/self-hosted-runner.md#auth-errors-in-runner-logs)

[Storage errors](/docs/help/troubleshooting/self-hosted-runner.md#storage-errors)

[Image pull failures](/docs/help/troubleshooting/self-hosted-runner.md#image-pull-failures)

[Helm upgrade fails](/docs/help/troubleshooting/self-hosted-runner.md#helm-upgrade-fails)

[Sizing guidelines](/docs/help/troubleshooting/self-hosted-runner.md#sizing-guidelines)

</details>

<details>

<summary><strong>Operational guides</strong><br>Terraform local development, state migration, and other one-time procedures</summary>

[Develop Terraform locally with remote state](/docs/help/guides/develop-terraform-locally.md)

[Migrate Terraform state to Bluebricks](/docs/help/guides/migrate-terraform-state.md)

</details>

***

#### FAQs

<details>

<summary>What is the difference between an artifact and a blueprint?</summary>

An **artifact** is a single Infrastructure as Code (IaC) component: one Terraform module, one Helm chart, one CloudFormation template, one Bicep template, or one generic container. Artifacts are not directly deployable.

A **blueprint** is a deployable unit composed of one or more packages (artifacts or other blueprints). Blueprints define relationships between packages, wire inputs and outputs, and expose an interface to the deployer.

For the full explanation, see [Packages](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages).

</details>

<details>

<summary>What is the difference between a collection and an environment?</summary>

A **collection** is the target: it groups a cloud account, RBAC rules, properties, secrets, and policies into a single unit.

An **environment** is the workflow that deploys a blueprint to a collection. Each environment execution creates a run.

For details, see [Collections](https://docs.bluebricks.co/bluebricks-documentation/orchestration/collections) and [Environments](https://docs.bluebricks.co/bluebricks-documentation/orchestration/deployments).

</details>

<details>

<summary>What IaC tools does Bluebricks support?</summary>

Bluebricks supports five artifact types:

* **Terraform** and **OpenTofu** (with version control and state management)
* **Helm** (Kubernetes package manager)
* **CloudFormation** (AWS native)
* **Bicep** (Azure native)
* **Generic** (any containerized workflow)

See the [Artifacts Overview](https://docs.bluebricks.co/bluebricks-documentation/orchestration/packages/artifacts-overview) for details on each type.

</details>

<details>

<summary>How do I enable pre-release versions?</summary>

Pre-release package versions are disabled by default. Your organization admin can enable them in the organization settings. Once enabled, pre-release versions appear alongside stable versions when installing blueprints.

</details>

<details>

<summary>How do I check my CLI version and authentication status?</summary>

Run these two commands:

```bash
bricks --version
bricks whoami
```

`bricks --version` shows the installed CLI version. `bricks whoami` confirms your current authentication status and user ID.

</details>

<details>

<summary>Can I use Bluebricks without Kubernetes?</summary>

Yes. Kubernetes is only required if you use the self-hosted runner (BDC) to execute deployments in your own infrastructure. Bluebricks also offers a managed runner option that does not require a Kubernetes cluster.

If you do need a lightweight Kubernetes setup, see [Orchestrator in a Box](https://docs.bluebricks.co/bluebricks-documentation/security/bluebricks-self-hosted-runner/orchestrator-in-a-box) for deploying K3s on a single VM.

</details>

<details>

<summary>How do I connect multiple cloud accounts?</summary>

Each collection connects to one cloud account. To manage multiple cloud accounts, create separate collections for each account. You can deploy the same blueprint across multiple collections, each targeting a different cloud account.

For setup instructions, see [Connect your Cloud](https://docs.bluebricks.co/bluebricks-documentation/getting-started/connect-your-cloud).

</details>

<details>

<summary>What are the network requirements for the self-hosted runner?</summary>

The Bluebricks Deployments Controller (BDC) requires outbound HTTPS access (port 443) to:

* `api.bluebricks.co` (Bluebricks API)
* `ghcr.io` (container images)
* `europe-docker.pkg.dev` (Helm chart registry)
* Your cloud provider APIs (AWS, GCP, Azure)

No inbound ports need to be opened. For the full list of requirements, see [Network Requirements](https://docs.bluebricks.co/bluebricks-documentation/resources/network-requirements).

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/help/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.