Zilla Gateway Deployment on EKS

This guide describes how to deploy a Zilla Platform Gateway on Amazon EKS.

This page assumes that the Zilla Platform Control & Management plane has already been deployed and initialized.

Prerequisites

• Zilla Platform deployed
• Zilla Platform bootstrap token
• Amazon EKS cluster
• AWS CLI configured with sufficient IAM permissions
• kubectl and helm installed

Create the Environment Namespace

Create a dedicated Kubernetes namespace for the environment:

kubectl create namespace <ENVIRONMENT_NAME>

Configure Access to AWS Secrets Manager (IRSA)

Zilla environment gateways can retrieve TLS certificates and other sensitive material from AWS Secrets Manager. This is achieved using IAM Roles for Service Accounts (IRSA).

Create IAM Policy for Secrets Access

Create an IAM policy allowing read access to Secrets Manager:

cat <<EOF > zilla-secrets-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:${AWS_REGION}:$(aws sts get-caller-identity --query Account --output text):secret:*"
    }
  ]
}
EOF

aws iam create-policy \
  --policy-name ZillaGatewaySecretsPolicy \
  --policy-document file://zilla-secrets-policy.json

Create IAM Role for IRSA

Create an IAM role that can be assumed by the environment gateway service account.

# Get OIDC provider URL
OIDC_PROVIDER=$(aws eks describe-cluster --name ${CLUSTER_NAME} --region ${AWS_REGION} \
  --query 'cluster.identity.oidc.issuer' --output text | sed 's|https://||')

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

# Create trust policy for the service account
cat <<EOF > trust-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${ACCOUNT_ID}:oidc-provider/${OIDC_PROVIDER}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "${OIDC_PROVIDER}:sub": "system:serviceaccount:<ENVIRONMENT_NAME>:<ENVIRONMENT_NAME>-zilla-platform-environment",
          "${OIDC_PROVIDER}:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name ZillaGatewayRole \
  --assume-role-policy-document file://trust-policy.json

# Attach the secrets policy
aws iam attach-role-policy \
  --role-name ZillaGatewayRole \
  --policy-arn arn:aws:iam::${ACCOUNT_ID}:policy/ZillaGatewaySecretsPolicy

# Get the role ARN for use in values.yaml
export ROLE_ARN="arn:aws:iam::${ACCOUNT_ID}:role/ZillaGatewayRole"
echo "Role ARN: $ROLE_ARN"

Configure Environment Values

Update environment-values.yaml with IRSA and vault configuration

# environment-values.yaml
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::<ACCOUNT_ID>:role/ZillaGatewayRole"

configs:
  zilla.yaml:
    content: |
      name: "gateway"
      vaults:
        server:
          type: aws-secrets
          options:
            aliases:
              example.aklivity.io: arn:aws:secretsmanager:us-east-1:YOUR_ACCOUNT_ID:secret:YOUR_SECRET_NAME

Note

Update the role ARN with your actual account ID and the aliases section with your actual secret ARNs.

Deploy the Gateway

Deploy the gateway using the environment Helm chart:

helm install <ENVIRONMENT_NAME> oci://ghcr.io/aklivity/charts/zilla-platform-environment \
  -n <ENVIRONMENT_NAME> \
  -f environment-values.yaml \
  --set bootstrapToken="${BOOTSTRAP_TOKEN}" \
  --set platformURI="https://platform.${DOMAIN}" \
  --set licenseKey="${ZILLA_PLATFORM_LICENSE_KEY}" \
  --set kubernetes.distribution="eks"

Info

The gateway pod will automatically receive AWS credentials via IRSA to access secrets from AWS Secrets Manager (if configured).

Verify Deployment

kubectl get pods -n <ENVIRONMENT_NAME>