Prerequisites

Every example assumes the same starting point. Set this up once and the walkthroughs will run straight through.

On your machine

Tool	Why
kubectl	Applying models and reaching services through port forwards
helm	Installing the operator and server
Go 1.26 or later	Running ossiectl for model generation and validation
jq	Reading the JSON responses in the verification steps
A MySQL client	Only for StarRocks stacks, to run catalog setup and read governed views
aws CLI	Only for stacks that use AWS Glue or S3

Check your context points at the right cluster before you begin.

kubectl config current-context

A Kubernetes cluster

Any cluster works. The examples were written and verified on Amazon EKS, and the Data on EKS blueprints are a quick way to get a cluster with a query engine already running.

You need enough room for the operator and server, which are small, plus whichever engine and catalog the example uses, which are not. The local laptop stack is the exception and manages its own resources.

A query engine

One of the following, reachable from the cluster.

StarRocks in shared data mode, with a front end that speaks the MySQL protocol. This is the reference engine.

Trino with a coordinator reachable over HTTP.

The engine does not have to run in the same cluster as the operator. It only has to be reachable at a host and port, with credentials.

Container images

Published on Amazon ECR Public, multi-arch for linux/amd64 and linux/arm64. No registry setup and no build.

public.ecr.aws/data-on-eks/semantic-operator/manager:v0.1.1
public.ecr.aws/data-on-eks/semantic-operator/server:v0.1.1

These are the chart defaults, so a plain helm install pulls them and no image flags are needed.

To run a build of your own instead, push to any registry your cluster can pull from. The docker-push target builds both images under <your-registry>/semantic-operator/.

make docker-build docker-push REGISTRY=<your-registry> TAG=<tag>

Then point the chart at them. The chart uses each repository exactly as you write it, so match the paths the push produced.

--set image.manager.repository=<your-registry>/semantic-operator/manager \
--set image.server.repository=<your-registry>/semantic-operator/server \
--set image.tag=<tag>

For Amazon ECR, authenticate first and create the repositories once. Pass the region, which the ECR targets read from AWS_REGION.

make ecr-create ecr-login REGISTRY=<acct>.dkr.ecr.<region>.amazonaws.com AWS_REGION=<region>

Use the same TAG value in the Helm install. A tag mismatch is the most common reason a first install sits in ImagePullBackOff.

Database credentials

The operator and the server want different database users, because they need different rights. The operator reads metadata and creates views. The server only reads data.

Component	Grants it needs
Operator	Read metadata on the model schemas, plus create and drop views in one schema
Server	SELECT on the schemas the model binds

You can start with a single user for both while trying things out, then split them with engine.manager.* and engine.server.* before anyone relies on it. See Access and credentials for the full matrix.

How you will reach the services

Every example uses kubectl port-forward. The server’s Service is ClusterIP and the chart refuses to publish it externally without an explicit override, because a load balancer in front of a server that trusts a role header is an unauthenticated query endpoint.

kubectl -n semantic-system port-forward svc/semantic-operator-server 8090:8090

If a port forward stops responding partway through a walkthrough, kill it and start it again. It is the most common cause of a confusing failure.

pkill -f 'kubectl.*port-forward'

Next

Pick a stack from Choosing an example, or go straight to Retail on Glue and StarRocks, which is the reference walkthrough.