> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.deepgram.com/docs/aws-k8s/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server.

# Amazon Web Services

Deploying Deepgram on Amazon Web Services (AWS) requires some preparation. In this section, you will learn how to provision a managed Kubernetes Cluster where you will deploy Deepgram products. You will need to perform some of these steps in the AWS Management Console and some in your local terminal.

# Prerequisites

Make sure you have completed the requirements in the [Self-Hosted Introduction](/docs/self-hosted-introduction).

## `kubectl`

The Kubernetes command-line tool, `kubectl`, allows you to run commands against Kubernetes clusters. You can use `kubectl` to deploy applications, inspect and manage cluster resources, and view logs.

Install locally using [the official Kubernetes guides](https://kubernetes.io/docs/tasks/tools/#kubectl) .

## AWS CLI

The [AWS CLI](https://aws.amazon.com/cli/) provides programmatic access to manage your AWS services. Certain steps in this guide are enabled by this tool, although many of the same actions can be performed manually in the AWS Console.

1. Follow the [installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to install the CLI locally.

2. Once installed, follow the [setup guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html) to configure the CLI with access to your AWS account. When configuring, set the default region to `us-west-2`.

   > **Info**
   >
   > ## Choosing a Region
   >
   > The templates and steps in this guide provision resources in the AWS `us-west-2` region.
   >
   > If you would like to deploy to a different region, make sure to specify your desired region when running `aws configure`, and adjust templates and steps in this guide accordingly.

## Cluster Management with `eksctl`

[`eksctl`](https://eksctl.io/) is the official CLI for Amazon EKS. It simplifies creating and managing clusters by creating subnets, managed node groups, service accounts, and other resources to integrate with your cluster.

Certain steps in this guide are enabled by this tool, although many of the same actions can be performed manually in the AWS Console. See the [installation guide](https://eksctl.io/installation) for details on how to install the latest version locally.

> **Warning**
>
> Make sure to install the latest version of `eksctl`. Do not use the version available through your package manager (e.g. `apt`, `dnf`), which may be an older release that is missing features used in this guide.
>
> Version `>=0.192.0` is required to create EKS clusters with nodes using EKS accelerated AMIs.

## Kubernetes Packages with `helm`

[Helm](https://helm.sh/) is the package manager for Kubernetes. A package in Kubernetes is defined by a Helm Chart, which helps you define, install, and upgrade even the most complex Kubernetes application.

We use Helm to install several components in this guide. See the [installation guide](https://helm.sh/docs/intro/install/) for details on how to install locally.

# Creating a Cluster

Amazon Elastic Kubernetes Service (Amazon EKS) is a managed Kubernetes service to run Kubernetes in the AWS cloud. In the cloud, Amazon EKS automatically manages the availability and scalability of the Kubernetes control plane nodes responsible for scheduling containers, managing application availability, storing cluster data, and other key tasks.

1. Download a `ClusterConfig` template from Deepgram's [self-hosted resources](https://github.com/deepgram/self-hosted-resources/tree/main/charts/deepgram-self-hosted/samples/). For example, [here](https://github.com/deepgram/self-hosted-resources/blob/main/charts/deepgram-self-hosted/samples/01-basic-setup-aws.cluster-config.yaml) is a template for a basic setup on AWS.

   1. Set the cluster name (`metadata.name`) and region according to your needs.
   2. Ensure that the IAM role name for Amazon EFS is unique in your AWS account `iam.serviceAccounts[1].roleName`.
   3. Modify each managed node group's `desiredCapacity` according to your needs. You may wish to consult your Deepgram Account Representative in planning your cluster's capacity.

2. Create a new Kubernetes cluster in Amazon EKS using the `ClusterConfig` manifest. This `eksctl` command will create several [AWS CloudFormation Stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html), which manage the inter-connected creation of a cluster, dedicated VPC, dedicated IAM, node groups, and other necessary resources.

   **`Shell`**

   ```shell Shell
   eksctl create cluster -f PATH_TO_CLUSTER_CONFIG_YAML
   ```

   > **Info**
   >
   > Make sure to replace the `PATH_TO_CLUSTER_CONFIG_YAML` placeholder with the path to the template file you downloaded on your local machine.

3. Record metadata from your new cluster in shell variables for use in future steps.

   **`Shell`**

   ```shell Shell
   CLUSTER_NAME="deepgram-self-hosted-cluster" # Replace name if modified in your ClusterConfig under `metadata.name`
   CLUSTER_REGION="us-west-2" # Replace name if modified in your ClusterConfig under `metadata.region`
   EFS_CSI_DRIVER_ROLE_NAME="efs-csi-driver-role" # Replace name if modified in your ClusterConfig under `iam.serviceAccounts`
   CAS_SVC_ACCT_NAME="cluster-autoscaler-sa" # Replace name if modified in your ClusterConfig under `iam.serviceAccounts`
   CAS_ROLE_NAME="cluster-autoscaler-role" # Replace name if modified in your ClusterConfig under `iam.serviceAccounts`
   CLUSTER_VPC_ID=$(
      aws eks describe-cluster \
         --name $CLUSTER_NAME \
         --query 'cluster.resourcesVpcConfig.vpcId' \
         --output text
   )
   ```

4. Create (or retrieve existing) an [Amazon Elastic File System](https://aws.amazon.com/efs/) (EFS) to store Deepgram model files and share them across multiple Deepgram Engine pods.

   **`Shell`**

   ```shell Shell
    FS_ID=$(
      aws efs create-file-system \
          --encrypted \
          --creation-token "$CLUSTER_NAME-resources" \
          --tags Key=Name,Value="$CLUSTER_NAME-resources" \
                  Key=associated-cluster-name,Value=$CLUSTER_NAME \
          --query 'FileSystemId' \
          --output text \
      || \
      aws efs describe-file-systems \
          --query "FileSystems[?Tags[?Key == 'associated-cluster-name' && Value == '$CLUSTER_NAME']].FileSystemId | [0]" \
          --output text
    )
   ```

5. Install the Amazon EFS CSI driver to allow nodes within your cluster to access the EFS you created. Use the service account role we created via our `ClusterConfig` file, and wait until installation is complete.

   **`Shell`**

   ```shell Shell
   csi_svc_acct_role_arn=$(
      aws iam get-role \
         --role-name $EFS_CSI_DRIVER_ROLE_NAME \
         --query 'Role.Arn' \
         --output text
   )
   eksctl create addon \
       --cluster $CLUSTER_NAME \
       --name aws-efs-csi-driver \
       --version latest \
       --service-account-role-arn $csi_svc_acct_role_arn \
       --force
    aws eks wait addon-active \
       --cluster-name $CLUSTER_NAME \
       --addon-name aws-efs-csi-driver
   ```

6. `eksctl` automatically creates several [security groups](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html) when it provisions your cluster. One of these security groups facilitates communication between AWS-managed nodes and other AWS resources. Find this security group and record its ID for the next step.

   **`Shell`**

   ```shell Shell
   ng_name=$(
       aws eks list-nodegroups \
       --cluster-name $CLUSTER_NAME \
       --query 'nodegroups[0]' \
       --output text
   )
   lt_id=$(
       aws eks describe-nodegroup \
           --cluster-name $CLUSTER_NAME \
           --nodegroup-name $ng_name \
           --query 'nodegroup.launchTemplate.id' \
           --output text
   )
   sg_ids=$(
       aws ec2 describe-launch-template-versions \
           --launch-template-id $lt_id \
           --query 'LaunchTemplateVersions[0].LaunchTemplateData.SecurityGroupIds[*]' \
           --output text
   )
   while read -r sg_id; do
       sg_ingress_rule=$(
           aws ec2 describe-security-groups \
               --group-ids $sg_id \
               --query 'SecurityGroups[0].IpPermissions[?contains(UserIdGroupPairs[*].GroupId, `'$sg_id'`)].IpProtocol' \
               --output text
       )
       if [[ $sg_ingress_rule == "-1" ]]; then
           MODEL_ACCESS_SG_ID=$sg_id
           break
       fi
   done <<< "$sg_ids"
   ```

7. Create mount targets on the EFS with the proper security group. This will allow all Deepgram Engine pods shared access to the EFS to read the model files that will be stored there.

   **`Shell`**

   ```shell Shell
   subnet_ids=$(
       aws eks describe-cluster \
           --name $CLUSTER_NAME \
           --query "cluster.resourcesVpcConfig.subnetIds" | \
       jq -r '.[]'
   )

   while read -r subnet_id; do
       aws efs create-mount-target \
           --file-system-id $FS_ID \
           --subnet-id $subnet_id \
           --security-groups $MODEL_ACCESS_SG_ID \
           --no-cli-pager
   done <<< "$subnet_ids"
   ```

8. Record the Role ARN that will be used later to Install the [Kubernetes Autoscaler](https://github.com/kubernetes/autoscaler/tree/master), a component that automatically adjusts the size of a Kubernetes Cluster so that all pods have a place to run and there are no unneeded nodes.

   **`Shell`**

   ```shell Shell
   CAS_SVC_ACCT_ROLE_ARN=$(
       aws iam get-role \
           --role-name $CAS_ROLE_NAME \
           --query 'Role.Arn' \
           --output text
   )
   ```

9. Create a dedicated namespace for Deepgram resources.

   **`Shell`**

   ```shell Shell
   kubectl create namespace dg-self-hosted
   kubectl config set-context --current --namespace=dg-self-hosted
   ```

# Configure Kubernetes Secrets

Deepgram strongly recommends following [best practices for configuring Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). Please refer to [Securing Your Cluster](/docs/securing-your-cluster) for more details.

The `deepgram-self-hosted` Helm chart takes two Secret references. One is a set of distribution credentials that allow the cluster to pull images from Deepgram's container image repository. The other is your self-hosted API key that licenses each Deepgram container that is created.

1. Complete the [Self Service Licensing & Credentials](/docs/self-hosted-self-service-tutorial) guide to generate distribution credentials and a self-hosted API key.

2. If using an external Secret store provider, configure cluster access to these two Secrets, naming them `dg-regcred` (distribution credentials) and `dg-self-hosted-api-key`.

3. If not using an external Secret store provider, create the Secrets manually in your cluster.

   1. Using the distribution credentials username and password generated in the Deepgram Console, create a Kubernetes Secret named `dg-regcred`.

      ```shell Shell
      kubectl create secret docker-registry dg-regcred \
          --docker-server=quay.io \
          --docker-username='QUAY_DG_USER' \
          --docker-password='QUAY_DG_PASSWORD'
      ```

      > **Info**
      >
      > Replace the placeholders `QUAY_DG_USER` and `QUAY_DG_PASSWORD` with the distribution credentials you generated in the [Self Service Licensing & Credentials](/docs/self-hosted-self-service-tutorial) guide.

   2. Create a Kubernetes Secret named `dg-self-hosted-api-key` to store your self-hosted API key.

      ```shell Shell
      kubectl create secret generic dg-self-hosted-api-key \
          --from-literal=DEEPGRAM_API_KEY='YOUR_API_KEY_HERE'
      ```

      > **Info**
      >
      > Replace the placeholder `YOUR_API_KEY_HERE` with the Deepgram API key you generated in the [Self Service Licensing & Credentials](/docs/self-hosted-self-service-tutorial) guide.

# Deploy Deepgram

Deepgram maintains the official `deepgram-self-hosted` Helm Chart. You can reference the [source](https://github.com/deepgram/self-hosted-resources/blob/main/charts/deepgram-self-hosted/README.md) and [Artifact Hub listing](https://artifacthub.io/packages/helm/deepgram-self-hosted/deepgram-self-hosted) for more details. We'll use this Chart to facilitate deploying Deepgram services in your self-hosted environment.

1. [Fetch the repository info](https://github.com/deepgram/self-hosted-resources/blob/main/charts/deepgram-self-hosted/README.md#get-repository-info).

   **`Shell`**

   ```shell Shell
   helm repo add deepgram https://deepgram.github.io/self-hosted-resources
   helm repo update
   ```

2. Download a `values.yaml` template from Deepgram's [self-hosted resources](https://github.com/deepgram/self-hosted-resources/tree/main/charts/deepgram-self-hosted/samples/). For example, [here](https://github.com/deepgram/self-hosted-resources/blob/main/charts/deepgram-self-hosted/samples/01-basic-setup-aws.values.yaml) is a template for a basic setup on AWS.

3. In your `values.yaml`, modify the `scaling.replicas.{api,engine}` values to match your set the initial number of replicas when your cluster is created. The capacities were defined previously with `desiredCapacity` in your `cluster-config.yaml` file.

   > **Info**
   >
   > If you want to enable pod autoscaling in your cluster, reach out to your Deepgram Account Representative to discuss whether soft or hard limits make sense for your use case, and what values to use for scaling your cluster based on traffic demands.

4. In your `values.yaml` file, insert your Amazon EFS ID into the `engine.modelManager.volumes.aws.efs.fileSystemId` value. You can get the ID from the shell variable you created previously.

   **`Shell`**

   ```shell Shell
   echo $FS_ID
   ```

   **`yaml`**

   ```yaml yaml
   engine:
     modelManager:
       volumes:
         aws:
           efs:
             enabled: true
             fileSystemId: fs-xxxxxxxxxxxxxxxx # Replace with your EFS ID
   ```

5. Your Deepgram Account Representative will have provided you with a list of links to models for inference (file extension `.dg`). In your `values.yaml` file, insert each of these model links in the `engine.modelManager.models.links` list.

   **`yaml`**

   ```yaml yaml
   engine:
     modelManager:
       models:
         links:
           - https://link-to-model-1.dg # Replace these links with those provided to you
           - https://link-to-model-2.dg #   by your Deepgram Account Representative.
           - https://link-to-model-3.dg
           - ...
   ```

6. In your `values.yaml` file, insert the AWS Role ARN to be used by the Cluster Autoscaler. If needed, adjust the cluster name and region as well.

   **`Shell`**

   ```shell Shell
   echo $CAS_SVC_ACCT_NAME
   echo $CAS_SVC_ACCT_ROLE_ARN
   echo $CLUSTER_NAME
   echo $CLUSTER_REGION
   ```

   **`yaml`**

   ```yaml yaml
   cluster-autoscaler:
     enabled: true
     rbac:
       serviceAccount:
         # Name of the CAS IAM Service Account
         name: "cluster-autoscaler-sa"
         annotations:
           # Replace with the AWS Role ARN configured for the Cluster Autoscaler
           eks.amazonaws.com/role-arn: "arn:aws:iam::000000000000:role/MyRoleName"
     autoDiscovery:
       # Replace if needed
       clusterName: "deepgram-self-hosted-cluster"  
     # Replace if needed
     awsRegion: "us-west-2"
   ```

7. Install the Helm Chart with your `values.yaml` file.

   **`Shell`**

   ```shell Shell
   helm install deepgram deepgram/deepgram-self-hosted \
       -f my-values.yaml \
       --namespace dg-self-hosted \
       --atomic \
       --timeout 1h 
   # Monitor the installation in a separate shell
   watch kubectl get all
   ```

   > **Warning**
   >
   > Resource limits, taints, and other constraints may limit Pod scheduling. If a Pod is not able to be scheduled, you can see its status and a list of associated events with `kubectl describe pod <pod-name>`.

# Test Your Deepgram Setup with a Sample Request

Test your Deepgram deployment on Amazon EKS with an audio file.

1. Launch an ephemeral pod to send your test request from.

   **`Shell`**

   ```shell Shell
   kubectl run --namespace dg-self-hosted api-client \
       --stdin --tty --rm \
       --image=curlimages/curl \
       -- /bin/sh
   ```

2. Inside the ephemeral pod, download a sample file from Deepgram (or supply your own file).

   **`Shell`**

   ```shell Shell
   wget https://dpgr.am/bueller.wav
   ```

3. Send your audio file to your local Deepgram setup for transcription.

   **`Shell`**

   ```shell Shell
   curl \
       -X POST \
       --data-binary @bueller.wav \
       "http://deepgram-api-external.dg-self-hosted.svc.cluster.local:8080/v1/listen?model=nova-3&smart_format=true"
   ```

   > **Info**
   >
   > If needed, adjust pieces of the above command:
   >
   > * the query parameters to match the directions from your Deepgram Account Representative
   > * the service name `deepgram-api-external`
   > * the namespace `dg-self-hosted`

You should receive a JSON response with the transcript and associated metadata. Congratulations - your self-hosted setup is working!

# Next Steps

Your Deepgram services are accessible within your cluster via the `deepgram-api-external` Service that was created by the Helm Chart.

You may consider configuring additional ingress with an [AWS Application Load Balancer](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) to access your services. Note that your installation will automatically load balance any received requests within the cluster to distribute load evenly. The load balancer would primarily serve as the ingress endpoint into the cluster.

---

What’s Next

Now that you have a basic Deepgram setup working, take some time to learn about building up to a production-level environment, as well as helpful Deepgram add-on services.

* [Securing Your Cluster](/docs/securing-your-cluster)
* [Scaling and Deployment Strategies](/docs/scaling-and-deployment-strategies)
* [Self-Hosted Add Ons](/docs/self-hosted-add-ons)

> With Kubernetes