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

# Kubernetes deployment guide for Maia runners

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

export const m_runner = "Maia runner";

export const maia = "Maia";

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["AWS", "Azure", "Google Cloud"]} />

This document provides an overview of Kubernetes deployment options for {m_runner}s. For cloud-specific architecture decisions and implementation details, see:

* [EKS deployment guide](/docs/guides/eks-deployment-guide).
* [AKS deployment guide](/docs/guides/aks-deployment-guide).
* [GKE deployment guide](/docs/guides/gke-deployment-guide).

Kubernetes deployment is one of several options for running {m_runner}s in your own infrastructure (Hybrid SaaS model). This approach offers:

* **Standardized deployment** via Helm charts.
* **Native cloud authentication** (AWS IRSA, Azure Managed Identity, GCP Workload Identity).
* **Horizontal pod autoscaling** (available on EKS and AKS, not available in ECS/ACI alternatives).
* **Platform portability** across AWS, Azure, Google Cloud, and self-managed Kubernetes clusters.

<Note>
  This document is not a step-by-step guide or tutorial, but rather an overview of what a Kubernetes administrator needs to know to deploy and manage {m_runner}s. We assume you have a working knowledge of Kubernetes, and have existing Kubernetes infrastructure, before attempting this deployment.
</Note>

***

## When to choose Kubernetes

Choose Kubernetes for {m_runner} deployment when:

* You have existing Kubernetes expertise and infrastructure.
* You need autoscaling capabilities (EKS, AKS, and GKE provide HPA support).
* You want standardized deployment across multiple cloud providers.
* You require integration with existing Kubernetes monitoring and security tooling.

Alternatives to consider:

* [Matillion Full SaaS](/docs/guides/runner-overview#matillion-full-saas): Matillion manages all infrastructure (fastest deployment).
* [AWS ECS Fargate](/docs/guides/aws-fargate-manual-runner-setup): AWS-native container deployment without Kubernetes management.
* [Azure Container Instances/Apps](/docs/guides/azure-arm-runner-install): Azure-native container deployment without Kubernetes management.

***

## Prerequisites

### Required tools

* [Kubernetes cluster](https://kubernetes.io/) 1.21+ (EKS, AKS, or self-managed).
* [kubectl](https://kubernetes.io/docs/tasks/tools/) configured with cluster admin permissions.
* [Helm 3.x](https://helm.sh/docs/intro/install/) for application deployment.

### Maia account

Before deploying, create a {m_runner} in {maia} to obtain:

* Account ID.
* {m_runner} ID.
* OAuth Client ID and Secret.
* Region (us1 or eu1).

For details, read [Create a {m_runner}](/docs/guides/create-a-runner#prerequisites).

***

## Cloud provider deployment guides

### Amazon EKS

For AWS deployments, the EKS guide covers:

* IAM Roles for Service Accounts (IRSA) for credential-free AWS access.
* VPC architecture decisions (new vs. existing, public vs. private cluster).
* Worker node sizing and autoscaling strategies.
* CloudWatch monitoring integration.
* EKS-specific cost optimization.

Read the [EKS deployment guide](/docs/guides/eks-deployment-guide) for details.

### Azure AKS

For Azure deployments, the AKS guide covers:

* Workload Identity/Managed Identity for credential-free Azure access.
* VNet architecture decisions (new vs. existing, public vs. private cluster).
* Node pool sizing and autoscaling strategies.
* Azure Monitor integration.
* AKS-specific cost optimization.

Read the [AKS deployment guide](/docs/guides/aks-deployment-guide) for details.

### Google Cloud GKE

For Google Cloud deployments, the GKE guide covers:

* Workload Identity for credential-free Google Cloud access.
* VPC architecture decisions (new vs. existing, public vs. private cluster).
* Node pool sizing and autoscaling strategies.
* Cloud Monitoring integration.
* GKE-specific cost optimization.

Read the [GKE deployment guide](/docs/guides/gke-deployment-guide) for details.

### Self-managed Kubernetes

For self-managed Kubernetes clusters (customer-managed control plane in cloud or other environments) you need to consider:

**Container registry:** Use AWS ECR Public (no authentication required).

* `public.ecr.aws/matillion/etl-agent:stable`
* `public.ecr.aws/matillion/etl-agent:current`

**Authentication:** OAuth credentials stored in Kubernetes Secrets.

**Deployment:** Use the standard Helm chart from the [deployment library](https://github.com/matillion-public/deployment-library/tree/main/agent/helm).

**Other considerations:**

* Native cloud authentication (IRSA, Workload Identity) not available for self-managed clusters.
* Use OAuth credentials for Matillion control plane authentication.
* Ensure outbound HTTPS connectivity to Matillion regional endpoints.
* Horizontal Pod Autoscaler supported (requires metrics server).
* Cluster Autoscaler availability depends on your infrastructure provider.

<Note>
  For managed Kubernetes services on other cloud providers, contact Matillion for platform availability.
</Note>

***

## Container images

{m_runner} images are available in cloud-specific container registries:

| Cloud provider                            | Image repository                                 | Tags                  |
| ----------------------------------------- | ------------------------------------------------ | --------------------- |
| **AWS** (EKS)                             | `public.ecr.aws/matillion/etl-agent`             | `:stable`, `:current` |
| **Azure** (AKS)                           | `matillion.azurecr.io/cloud-agent`               | `:stable`, `:current` |
| **Google Cloud** (GKE) for US deployments | `us-docker.pkg.dev/maia-492711/maia-runners`     | `:stable`, `:current` |
| **Google Cloud** (GKE) for EU deployments | `europe-docker.pkg.dev/maia-492711/maia-runners` | `:stable`, `:current` |
| **Self-managed Kubernetes**               | `public.ecr.aws/matillion/etl-agent`             | `:stable`, `:current` |

Image tag strategy:

* **`:stable`** - Slower release cycle, maximum stability.
* **`:current`** - Faster release cycle, earlier access to new features.

Both tags are production-ready. Choose based on your preference for stability vs. early feature access.

The tag you select here **must** match the [version track](/docs/guides/runner-overview#maia-runner-version-tracks) configured for this {m_runner} in the runner manager. Mismatching the two can result in unexpected version behavior.

***

## Common Kubernetes deployment components

All Kubernetes deployments use these same core components.

### Helm charts

**Standard Helm chart** deploys:

* {m_runner} pods (deployment with configurable replicas).
* Kubernetes service (Prometheus metrics endpoint on port 8080).
* ConfigMaps ({m_runner} configuration).
* Secrets (OAuth credentials for Matillion control plane).
* ServiceAccount (for cloud-native authentication where available).

Read the [Helm charts documentation](https://github.com/matillion-public/deployment-library/tree/main/agent/helm).

### Prometheus metrics

{m_runner}s expose Prometheus-compatible metrics at `/actuator/prometheus` on port 8080:

* `app_version_info`: {m_runner} build version.
* `app_agent_status`: Running status (1=running, 0=stopped).
* `app_active_task_count`: Currently executing tasks.
* `app_active_request_count`: Active HTTP requests.
* `app_open_sessions_count`: Open data warehouse connections.

The Helm chart includes service discovery annotations for automatic Prometheus scraping.

### Security standards

All Kubernetes deployments implement pod security best practices:

* Run as non-root user (UID 65534).
* Read-only root filesystem.
* No privilege escalation.
* All Linux capabilities dropped.
* Seccomp profile applied (RuntimeDefault).

### Pre-deployment validation

The deployment library includes automated validation scripts in `agent/helm/checks/`:

* `run-check.sh`—orchestrator that:

  * Auto-discovers {m_runner} pods using Helm chart labels.
  * Performs cluster-level security scans.
  * Executes in-pod validation.

* `pre-deployment-check.sh`—validator that checks:

  * Python 3 and Java runtime availability.
  * Filesystem permissions.
  * Environment variables.
  * Network connectivity to Matillion control plane.
  * Security agents that might interfere (Crowdstrike, Prisma Cloud).

Usage:

```bash theme={null}
./agent/helm/checks/run-check.sh --namespace matillion --release matillion-agent
```

The output uses color-coded results (PASS, WARN, FAIL), with exit code `0` for success and `1` for failure.

***

## Next steps

* For AWS deployments, read the [EKS deployment guide](/docs/guides/eks-deployment-guide).
* For Azure deployments, read the [AKS deployment guide](/docs/guides/aks-deployment-guide).
* For Google Cloud deployments, read the [GKE deployment guide](/docs/guides/gke-deployment-guide).
* For implementation details, see the [Matillion deployment library](https://github.com/matillion-public/deployment-library).
* For {m_runner} concepts and architecture, read:

  * [{m_runner} overview](/docs/guides/runner-overview).
  * [Scaling best practices](/docs/guides/scaling-best-practices).