---
title: "Deploy Meko on AWS"
url: "https://docs.mekodata.ai/byoc/deploy-aws/"
---

# Deploy Meko on AWS

Run the Meko BYOC install command on EKS, register your sign-in URIs, and give the reconcile agent its token

Before you start, you have the [IAM keys](/byoc/prerequisites/aws-iam/), the [OpenAI key](/byoc/prerequisites/openai-key/), the [OIDC client](/byoc/prerequisites/identity-provider/), and a [prepared cluster](/byoc/prerequisites/kubernetes-network/).

## Get the install command

Register an environment of kind `meko` in the Meko console. The console shows an install command for it with the chart version and image tags of the current release already filled in. It also shows the reconcile agent's API key, **once**. Copy it into `AGENT_API_KEY` straight away. The console can revoke the key but can't show it again.

Your Meko contact gives you the console address and your license file. [Apply the license](/byoc/prerequisites/meko-license/) to the cluster, in the namespace named by `NS` in the command's header, before you run the command.

The command is a block of shell. It starts with a header of values, and the rest is pasted as it is.

## Edit the database definition

The database is a YugabyteDB universe that an operator creates from a definition file, the `Foundation`. The file ships in the Meko chart, in a proof-of-concept size and a production size. Pull the chart at the version in the install command (`CHART_VERSION`), using the Quay credentials from your license, and copy the file for your `SIZE`:

```sh
NS='<namespace>'   # the NS value in the install command
export HELM_REGISTRY_CONFIG="$(mktemp -d)/registry.json"   # keeps the token out of your own helm config
kubectl -n "$NS" get secret quay-registry-creds \
  -o go-template='{{index .data ".dockerconfigjson" | base64decode}}' >"$HELM_REGISTRY_CONFIG"
helm pull oci://quay.io/yugabyte/charts/meko --version <CHART_VERSION> --untar -d meko-chart
rm -r "$(dirname "$HELM_REGISTRY_CONFIG")"; unset HELM_REGISTRY_CONFIG

cp meko-chart/meko/foundation/meko-foundation-cr.yaml foundation-cr.yaml        # poc
cp meko-chart/meko/foundation/meko-foundation-cr-prod.yaml foundation-cr.yaml   # prod
```

The file is set up for Google Cloud, so change every value marked `REPLACE`:

| Field                                           | Set it to                                                                                                                                                                                                       |
|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `spec.yba.values.yugaware.defaultUser`          | A username, email, and **a new password** for the database's management account. Don't keep `Password#123`.                                                                                                     |
| `spec.yba.values.yugaware.storageClass`         | Your storage class, for example `meko-gp3`                                                                                                                                                                      |
| `YBProvider` `cloudInfo.kubernetesProvider`     | `eks`                                                                                                                                                                                                           |
| `YBProvider` `regions`                          | Your Region code and its zone codes, for example `us-east-1` with `us-east-1a`, `us-east-1b`, `us-east-1c`                                                                                                      |
| `YBProvider` zone `kubernetesStorageClass`      | Your storage class, in every zone                                                                                                                                                                               |
| `YBUniverse` `placementInfo`                    | The same Region and zones. They must match the provider. Put one node in each of three zones, or all three in one zone.                                                                                         |
| `spec.yba.values.image.repository`              | The repository Meko support names for the YugabyteDB Anywhere image. The robot in your license needs pull access to it.                                                                                         |
| `YBProvider` `kubernetesImageRegistry`          | The repository Meko support names for the database image. `ybSoftwareVersion` must be a tag in it.                                                                                                              |
| `YBUniverse` `kubernetesOverrides.nodeSelector` | Optional, recommended for production: uncomment it and set the label of your database node group, for example `eks.amazonaws.com/nodegroup: meko-db`. A label that matches no node leaves the database pending. |

Leave the pull secret `quay-registry-creds` and the database version as they are. The license supplies the credentials for that pull secret.

Keep this file. Every rerun of the install applies it again, and an upgrade starts from it: you [copy your edits into the new release's file](/byoc/upgrade/#move-to-a-new-release).

## Fill in the header

Set `NS` to the namespace you applied your license in, `SIZE` to `poc` or `prod`, `FOUNDATION_CR` to the path of your edited file, and the values you collected:

```sh
NS='<namespace>'     # filled in by the console; the namespace your license is applied in
SIZE='poc'
FOUNDATION_CR='./foundation-cr.yaml'

BEDROCK_KEY='<aws access key id>'
BEDROCK_SECRET='<aws secret access key>'
BEDROCK_REGION=us-east-1
KB_S3_BUCKET='meko-kb-store'

LANGFUSE_S3_BUCKET='meko-traces-store'
LANGFUSE_S3_REGION='us-east-2'
LANGFUSE_S3_KEY='<aws access key id>'
LANGFUSE_S3_SECRET='<aws secret access key>'
LANGFUSE_OWNER_EMAIL='you@example.com'

OPENAI_KEY='<openai api key>'

OIDC_ISSUER_URL='https://idp.example.com/realms/meko'
OIDC_CLIENT_ID='<client id>'
OIDC_CLIENT_SECRET=''

PUBLIC_URL=''        # production: https://meko.example.com
ACM_CERT_ARN=''      # production: the certificate's ARN

AGENT_API_KEY='<shown once by the console>'
```

Leave the tags and `CHART_VERSION` as the console filled them. Leave `PUBLIC_URL` and `ACM_CERT_ARN` empty for a proof of concept. For production, set both. The install checks the header and stops before it creates anything if a required value is empty, or if the values contradict each other.

## Run it

Paste the whole command into a `bash` or `zsh` terminal that has `kubectl` pointed at the cluster, and `aws` signed in. The install runs in steps. It stops at the first one that fails, and it is safe to run again.

The steps are numbered as in the install's own messages, so an error such as `step 3: the database is not Ready` names the step below.

- **Before step 1.** The install checks the header and that your license's three Secrets are in `NS`. It stops if anything is missing, before it creates anything.
- **Step 1, secrets.** Creates the Secret that holds the reconcile agent's key.
- **Step 2, load balancer.** Creates the internal ALB and waits for its address, which takes a few minutes. It then prints Meko's address and the two URIs to register:
  
  ```text
  Register these on your OIDC client before the first sign-in:
    redirect URI:             <address>/api/v1/auth/oidc/callback
    post-logout redirect URI: <address>
  ```
  
  Register them in your [identity provider](/byoc/prerequisites/identity-provider/) now if you haven't. In production, create the DNS record for your host name too.
- **Step 2b, bucket CORS.** Part of step 2. Adds the rule that lets the UI upload to the knowledge-base bucket, using your AWS credentials. If it can't, it prints the rule for you to add.
- **Step 3, database.** Installs the database operator and applies your definition. YugabyteDB takes 20 to 40 minutes to come up. The install waits up to an hour.
- **Step 4, Meko stack and reconcile agent.** Installs Meko with the values you set.

When it finishes, it prints `Installed SIZE=… into <namespace>`.

Note

To change a value later, change the header and run the install command again. Don't run `helm upgrade` on the Meko release by itself. See [Upgrade](/byoc/upgrade/).

## Give the agent its token

The environment shows as degraded in the console until the reconcile agent has an API key of its own, because the API server authenticates every call.

1. Sign in to Meko at the address as the [user you kept for the agent](/byoc/prerequisites/identity-provider/#create-a-user-for-the-reconcile-agent), not as yourself.
2. Open **Settings → API Keys** and create a key.
3. Store it for the agent and restart the agent. `<namespace>` is the namespace the install used, which it printed at the end:
   
   ```sh
   kubectl -n <namespace> create secret generic meko-reconcile-agent-token \
     --from-literal=meko-api-token=<key>
   kubectl -n <namespace> rollout restart deploy/meko-reconcile-agent
   ```

The datapacks the agent creates belong to its account. People see them when you share them from it. Invite emails are off, so a shared datapack appears under the recipient's incoming shares and nobody is emailed.

## Check the install

```sh
kubectl -n <namespace> rollout status deploy/meko-api-server
kubectl -n <namespace> get pods
kubectl -n <namespace> logs deploy/meko-reconcile-agent
```

From a network that can reach the ALB:

```sh
curl -sI <address> | head -1
```

A `200` or a redirect to your identity provider means the load balancer and the UI are up. Then sign in, and check that the environment shows as healthy in the console.

To connect an agent over MCP, use `<address>/mcp` with a key from **Settings → API Keys**.

## If something fails

| Symptom                                                   | Cause                                                                                                                                                                                         | Fix                                                                                                                                                               |
|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Stops at the start with "The Meko license is not applied" | One of the license's Secrets is missing from `NS`, or lacks its key. The message names it.                                                                                                    | Apply the license in `NS` as in [Apply your Meko license](/byoc/prerequisites/meko-license/#apply-the-license), then rerun.                                          |
| Stops at the start with "no alb IngressClass"             | The AWS Load Balancer Controller isn't installed.                                                                                                                                             | [Install it](/byoc/prerequisites/kubernetes-network/#aws-load-balancer-controller), then rerun.                                                                      |
| Stops at step 2 with "The ALB has no address yet"         | The private subnets lack the `kubernetes.io/role/internal-elb=1` tag, or the load balancer controller isn't healthy. `kubectl -n <namespace> describe ingress meko-ui-ingress` shows why.     | [Tag the subnets](/byoc/prerequisites/kubernetes-network/#subnet-tags) or repair the controller, then rerun.                                                         |
| Uploads from the UI fail, but uploads through MCP work    | The bucket's CORS rule is missing.                                                                                                                                                            | Add the rule the install printed, as in [CORS on the knowledge-base bucket](/byoc/prerequisites/aws-s3-buckets/#cors-on-the-knowledge-base-bucket).                  |
| The database pods stay `Pending`                          | The nodes are too small, the `nodeSelector` label matches no node, or the storage class can't provision. `kubectl -n <namespace> describe foundation foundation` shows the operator's reason. | Add or enlarge nodes to the [size you chose](/byoc/prerequisites/requirements/#cluster), correct the label or the storage class in your definition file, then rerun. |
| Sign-in fails with a redirect error                       | The redirect URI at your identity provider doesn't match `<address>/api/v1/auth/oidc/callback` exactly.                                                                                       | Register the URI the install printed, exactly, in your [identity provider](/byoc/prerequisites/identity-provider/).                                                  |
| Memory features return nothing                            | `OPENAI_KEY` is invalid, or the project can't use `gpt-5-mini`.                                                                                                                               | Fix the key or the project's model access ([Get an OpenAI key](/byoc/prerequisites/openai-key/)), put the key in `OPENAI_KEY`, then rerun.                           |
| Knowledge-base uploads are never indexed                  | `BEDROCK_KEY` lacks a permission, or Titan embeddings aren't available in `BEDROCK_REGION`.                                                                                                   | [Check the keys](/byoc/prerequisites/aws-iam/#check-the-keys), enable the model in that Region, and rerun if you changed a key.                                      |
