> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suga.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Cluster (BYOC)

> Run Suga on your own Kubernetes infrastructure

BYOC allows you to run Suga on your own Kubernetes infrastructure while using the Suga dashboard for management. You get full control over where applications run while maintaining Suga's simplicity.

<Note>
  BYOC is part of an Enterprise agreement and is set up with our team. It is not something you enable yourself from the dashboard. This page describes how it works and what your cluster needs. To talk through it for your environment, [contact us](/support/contact).
</Note>

## BYOC vs Suga Cloud

| Aspect | Suga Cloud | BYOC |
| - | - | - |
| **Setup** | Zero infrastructure | You manage K8s cluster |
| **Control** | Suga manages | Full control |
| **Data Location** | Suga's infrastructure | Your infrastructure |
| **Regions** | US, Europe, Australia | Any region/cloud/on-prem |
| **Best For** | Most users | Enterprise, compliance, existing K8s |

## Prerequisites

* **Kubernetes 1.24+** with cluster-admin access
* **LoadBalancer support** - Cloud provider integration or MetalLB for bare metal
* **Default storage class** - Must support `ReadWriteOnce` access mode for volumes
* **Outbound internet access** - To pull container images and connect to Suga API

<Note>
  Suga automatically installs **Envoy Gateway** (Gateway API) and manages **TLS certificates** and **DNS records** during cluster initialization. You don't need to set these up.
</Note>

### Supported Platforms

GKE, EKS, AKS, self-managed, on-premises, DigitalOcean, Linode, Civo, and other K8s providers.

## Architecture

```mermaid theme={null}
graph LR
    dashboard[Suga Dashboard] --> backend[Suga Backend]
    backend -->|Kubernetes API| apiserver[K8s API Server<br/>Your Cluster]
    apiserver --> apps[Your Applications]
```

* **Direct API Connection** - Suga connects directly to your Kubernetes API server (no agent installed)
* **Encrypted Credentials** - Your cluster credentials are stored encrypted in Suga's database
* **Standard K8s API** - All operations use the Kubernetes REST API
* **Your Infrastructure** - Workloads and data run entirely in your cluster

## Setup

<Steps>
  <Step title="Add BYOC Cluster">
    Go to **Cluster** in the left sidebar and connect your cluster.

    Follow the guided setup to provide your cluster credentials. The UI will walk you through entering your API server URL and authentication details.
  </Step>

  <Step title="Verify Connection">
    After adding, the dashboard should show "Connected" with a green indicator. Suga will automatically initialize the cluster with Envoy Gateway and required components.
  </Step>
</Steps>

<Tip>
  Need help connecting your cluster? [Contact support](/support/contact) for assistance.
</Tip>

## Namespaces

Suga creates one namespace per environment, named `suga-` followed by the environment's ID:

```
suga-3f8a1c92-7b4e-4d21-9c05-6ea2f0b81d47
```

The name is not derived from the environment's display name, so an environment called "production" does not get a `suga-production` namespace. Find the ID in the environment's dashboard URL.

## Direct Cluster Access

With BYOC, you have full kubectl access. Set the namespace to the environment you want:

```bash theme={null}
export NS=suga-3f8a1c92-7b4e-4d21-9c05-6ea2f0b81d47

# List pods
kubectl get pods -n $NS

# View logs directly
kubectl logs my-api-xxxxx -n $NS

# Execute commands in pod
kubectl exec -it my-api-xxxxx -n $NS -- /bin/sh

# Port forward for debugging
kubectl port-forward svc/postgres 5432:5432 -n $NS
```

## Security Considerations

<AccordionGroup>
  <Accordion title="Credential Security">
    * Use a dedicated ServiceAccount with least-privilege permissions where possible
    * Rotate credentials periodically
    * Suga stores credentials encrypted at rest (AES-256-GCM)
    * All API communication is TLS-encrypted
  </Accordion>

  <Accordion title="Network Policies">
    Implement network policies to restrict traffic between namespaces. See Kubernetes documentation for examples.
  </Accordion>

  <Accordion title="Pod Security">
    Apply Pod Security Standards to Suga namespaces:

    ```bash theme={null}
    kubectl label namespace suga-<environment-id> \
      pod-security.kubernetes.io/enforce=baseline
    ```
  </Accordion>

  <Accordion title="Secrets">
    Suga stores secrets as Kubernetes Secrets. For enhanced security, use External Secrets Operator with your vault solution or enable Kubernetes encryption at rest.
  </Accordion>
</AccordionGroup>

## Cost

**Suga Platform:** Pricing for BYOC has not been set. [Contact us](/support/contact) for details.

**Your Infrastructure:** Kubernetes cluster costs depend on your cloud provider. Typical range: \$100-1500+/month depending on size.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.