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

# Installation

> How a Restate Cloud BYOC deployment is set up in your cloud account.

A BYOC region is a Restate Cloud data plane running in your cloud account. Setting one up is a collaborative process between you and Restate.

## Requesting a BYOC region

To get started, contact Restate with:

* **Cloud provider**: AWS, Azure, or GCP
* **Region**: the cloud provider region where you want the data plane deployed (e.g. `us-west-2`, `eu-west-1`, `eastus2`)

Restate will provide:

* **Foundation stack deployment instructions** — a CloudFormation quick-create URL (AWS), ARM template link (Azure), or equivalent for your provider
* **Region secret key** — a one-time token that authenticates the deployment agent with Restate's control plane

## Deploying the foundation

The foundation is the only layer you deploy manually. It creates the networking, secrets store, and deployment agent in your account. The remaining layers are provisioned automatically.

<Tabs>
  <Tab title="AWS">
    Restate provides a **CloudFormation quick-create link** that pre-fills the template URL and stack name. The link looks like this:

    ```
    https://<region>.console.aws.amazon.com/cloudformation/home
      ?region=<region>
      #/stacks/quickcreate
        ?templateUrl=<template-url>
        &stackName=restate-byoc-<your-name>
    ```

    Opening this link takes you directly to the CloudFormation "Quick create stack" page.

    <Steps>
      <Step title="Review the template">
        The template URL is pre-filled. You can expand **View template** to inspect the resources that will be created.

        The **stack name** is customizable — choose something meaningful to your team, such as `restate-byoc-production` or `restate-byoc-staging`.

        <Frame>
          <img src="https://mintcdn.com/restate-6d46e1dc/N07UCdvsQ4Pd2iHp/img/byoc/aws-quick-create-start.png?fit=max&auto=format&n=N07UCdvsQ4Pd2iHp&q=85&s=f62a4d3a68ba7d7d43493ad38ccb14a0" alt="CloudFormation Quick create stack form showing the pre-filled template URL and stack name" width="1952" height="1462" data-path="img/byoc/aws-quick-create-start.png" />
        </Frame>
      </Step>

      <Step title="Enter the region secret key">
        Under **Application Secrets**, paste the **region secret key** provided by Restate. This key is used once to authenticate the deployment agent with Restate's control plane.

        Leave the **Access Permissions** defaults as-is.

        <Frame>
          <img src="https://mintcdn.com/restate-6d46e1dc/N07UCdvsQ4Pd2iHp/img/byoc/aws-quick-create-params.png?fit=max&auto=format&n=N07UCdvsQ4Pd2iHp&q=85&s=222a70611a9ab5c2864bc589d2ad31c3" alt="CloudFormation parameters showing the region token input and access permission defaults" width="1952" height="1460" data-path="img/byoc/aws-quick-create-params.png" />
        </Frame>
      </Step>

      <Step title="Acknowledge capabilities and create">
        At the bottom of the page, check both IAM capability acknowledgement boxes. These are required because the template creates IAM roles for the deployment agent.

        Click **Create stack**.

        <Frame>
          <img src="https://mintcdn.com/restate-6d46e1dc/N07UCdvsQ4Pd2iHp/img/byoc/aws-quick-create-capabilities.png?fit=max&auto=format&n=N07UCdvsQ4Pd2iHp&q=85&s=11425512d5099211428f6d603a8f9b0f" alt="CloudFormation capabilities checkboxes and Create stack button" width="2420" height="1700" data-path="img/byoc/aws-quick-create-capabilities.png" />
        </Frame>
      </Step>
    </Steps>

    The stack creates:

    * A VPC with public and private subnets across availability zones
    * A secrets store (AWS Secrets Manager) for the region secret key
    * The deployment agent (an EC2 Auto Scaling Group) with scoped IAM roles
  </Tab>

  <Tab title="GCP">
    Restate provides the foundation as a Terraform module ([`nuonco/install-stacks`](https://github.com/nuonco/install-stacks), the `gcp/` directory) plus a generated `install.tfvars` and `backend.tf` for your install. You apply it into your own GCP project, using a Cloud Storage bucket you control for Terraform state. The deployment agent it creates then brings up everything else.

    <Steps>
      <Step title="Prerequisites">
        In the target GCP project, before you apply:

        * **Run as a project admin.** Authenticate the identity that will run Terraform and set it as your application-default credentials: `gcloud auth application-default login`. It needs to create VPC networking, GKE, service accounts and IAM bindings, Secret Manager secrets, Cloud DNS, and Artifact Registry, and to enable services.
        * **Enable the required APIs:** Compute Engine, Kubernetes Engine, Secret Manager, Cloud Resource Manager, Cloud DNS, and Artifact Registry.
        * **Attach a billing account** to the project.
        * **Create a Cloud Storage bucket you control** for Terraform state (private, with versioning enabled). Keep the state — while it is reconstructable, it is your record of the install.
        * **Check your organization policies.** Policies such as *"no public IPs on VMs"* or a *deny-egress* rule will block GKE and firewall provisioning. If one blocks the apply, override it at the project level (or coordinate with Restate) and retry.
      </Step>

      <Step title="Get your configuration">
        Clone the foundation module and drop in the two files Restate sends you:

        ```bash theme={null}
        git clone https://github.com/nuonco/install-stacks.git
        cd install-stacks/gcp
        # copy the install.tfvars and backend.tf Restate provided into this directory
        ```

        `install.tfvars` contains a `runner_api_token` that authenticates the deployment agent with Restate. Treat the file as a secret: transfer it over a secure channel and don't commit it (it ends up in Terraform state, which is why the state bucket must be private).
      </Step>

      <Step title="Configure state">
        Edit `backend.tf` to point at your state bucket. The `prefix` is already set to your install id — leave it:

        ```hcl theme={null}
        terraform {
          backend "gcs" {
            bucket = "<your-state-bucket>"
            prefix = "nuon/<your-install-id>"
          }
        }
        ```
      </Step>

      <Step title="Set the region-token placeholder">
        `install.tfvars` includes a required `restatecloudregiontoken_<your-install-id>` secret that ships **empty**. Set it to any non-empty placeholder before applying — if you leave it empty, `terraform apply` fails with `Field [payload] is required`:

        ```hcl theme={null}
        # in install.tfvars
        value = "placeholder"
        ```

        You do **not** put the real token here. Once the deployment agent is running, Restate injects the real region token into this secret automatically.
      </Step>

      <Step title="Deploy the foundation">
        ```bash theme={null}
        terraform init
        terraform apply -var-file=install.tfvars
        # you'll be prompted for gcp_project_id and gcp_region
        ```

        This creates only the foundation: VPC and networking, IAM, the region-token secret, and the deployment agent (a Compute Engine runner). The runner then phones home to Restate, which provisions the GKE cluster and all Restate components automatically — you do not run any further Terraform.

        Your `apply` finishing is the handoff point, not the end: bringing up the cluster and components takes roughly **30 minutes**. A follow-up `terraform plan` that shows only drift on the runner's `phone_home` trigger is expected and harmless.
      </Step>
    </Steps>

    <Info>
      Reach out to Restate to start onboarding and receive your configuration files.
    </Info>
  </Tab>

  <Tab title="Azure (Preview)">
    Restate provides an **ARM template deployment link** that guides you through a similar process in the Azure Portal.

    The template creates:

    * A VNet with public and private subnets
    * An Azure Key Vault for the region secret key
    * The deployment agent (a Virtual Machine Scale Set) with scoped Azure role assignments

    <Info>
      Azure support is in preview. Installation details will be documented here as the guided onboarding flow is finalized. Reach out to Restate for current instructions.
    </Info>
  </Tab>
</Tabs>

## Infrastructure

Once the foundation is in place, the deployment agent automatically provisions:

* A managed Kubernetes cluster (EKS on AWS, GKE on GCP, AKS on Azure)
* A container registry for Restate component images
* Certificate management (cert-manager with DNS validation)
* Service mesh (Linkerd) for in-cluster mTLS
* Network policies for workload isolation

This step requires no action from you. The deployment agent pulls provisioning jobs from Restate's control plane and applies them using Terraform within your account.

## Application

After the infrastructure is ready, the following Restate data plane components are deployed into the cluster:

* **Ingress proxy** — routes traffic from your services to Restate environments
* **Tunnel** — enables connectivity between Restate and services in other VPCs or networks
* **Restate operator** — manages Restate environment lifecycle (create, update, scale, delete)
* **Monitoring** — metrics collection and log aggregation

Once all three layers are deployed successfully, your BYOC region is activated and you can create Restate environments through the Restate Cloud console.

## Ongoing updates

After the initial deployment, Restate pushes updates to the infrastructure and application layers through the same deployment agent. Updates include:

* Kubernetes version upgrades (coordinated with you in advance)
* Restate component releases
* Security patches and node OS updates (automated via drift detection)

You do not need to re-deploy the foundation template for routine updates. Template updates are only needed when the foundation layer itself changes, which is rare.