EKS (Elastic Kubernetes Service)

Protocol: REST-JSON
Endpoint: http://localhost:4566/ (path-routed via JAX-RS)

EKS uses a standard REST API with JSON bodies — not the JSON 1.1 (X-Amz-Target) or Query protocol.

Supported Operations

Operation	Description
`CreateCluster`	Create a new EKS cluster
`DescribeCluster`	Describe a cluster by name
`ListClusters`	List all cluster names
`DeleteCluster`	Delete a cluster
`TagResource`	Add tags to a cluster
`UntagResource`	Remove tags from a cluster
`ListTagsForResource`	List tags on a cluster

Modes

Mock mode (`mock: true`)

Cluster metadata is stored in-process. No Docker containers are started. The cluster transitions directly to ACTIVE on creation. Use this in CI or whenever you only need the EKS API shape, not a real Kubernetes API server.

Real mode (`mock: false`, default)

Floci starts a k3s (rancher/k3s) container for each cluster. The k3s API server is exposed on a host port from the configured range (6500–6599). Once /readyz responds, the cluster transitions to ACTIVE and the CA certificate is extracted from the kubeconfig.

Docker socket required

Real mode starts privileged Docker containers. Mount the Docker socket and set the Docker network so containers can reach each other.

services:
  floci:
    image: floci/floci:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "4566:4566"
    environment:
      FLOCI_SERVICES_EKS_DOCKER_NETWORK: my_project_default

No port mapping needed for k3s ports

k3s containers bind their API server port (6500–6599) directly on the host via Docker — no ports: entry is required in docker-compose.yml. See Ports Reference for the full explanation.

Configuration

floci:
  services:
    eks:
      enabled: true
      mock: false                          # true = metadata only, no Docker
      provider: k3s                        # only k3s is supported
      default-image: "rancher/k3s:latest"
      api-server-base-port: 6500           # first port in the k3s API server range
      api-server-max-port: 6599
      data-path: ./data/eks                # host bind-mount root for cluster data
      docker-network: ""                   # inherits floci.services.docker-network if unset
      keep-running-on-shutdown: false      # leave k3s containers running after Floci stops

Environment Variables

Variable	Default	Description
`FLOCI_SERVICES_EKS_ENABLED`	`true`	Enable the EKS service
`FLOCI_SERVICES_EKS_MOCK`	`false`	Metadata-only mode (no Docker)
`FLOCI_SERVICES_EKS_DEFAULT_IMAGE`	`rancher/k3s:latest`	k3s Docker image
`FLOCI_SERVICES_EKS_API_SERVER_BASE_PORT`	`6500`	First port in the k3s API server range
`FLOCI_SERVICES_EKS_API_SERVER_MAX_PORT`	`6599`	Last port in the k3s API server range
`FLOCI_SERVICES_EKS_DATA_PATH`	`./data/eks`	Host bind-mount root for cluster data
`FLOCI_SERVICES_EKS_DOCKER_NETWORK`	(unset)	Docker network for k3s containers
`FLOCI_SERVICES_EKS_KEEP_RUNNING_ON_SHUTDOWN`	`false`	Leave k3s containers running after Floci stops

Mock mode (CI / tests)

Use FLOCI_SERVICES_EKS_MOCK=true when you only need the API shape:

# docker-compose.yml — CI / test environment
services:
  floci:
    image: floci/floci:latest
    environment:
      FLOCI_SERVICES_EKS_MOCK: "true"

ARN Format

arn:aws:eks:<region>:<accountId>:cluster/<clusterName>

Examples

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

# Create a cluster
aws eks create-cluster \
  --name my-cluster \
  --role-arn arn:aws:iam::000000000000:role/eks-role \
  --resources-vpc-config subnetIds=[],securityGroupIds=[] \
  --kubernetes-version 1.29

# Describe the cluster
aws eks describe-cluster --name my-cluster

# List clusters
aws eks list-clusters

# Tag a cluster
aws eks tag-resource \
  --resource-arn arn:aws:eks:us-east-1:000000000000:cluster/my-cluster \
  --tags env=dev,team=platform

# Delete a cluster
aws eks delete-cluster --name my-cluster

Java SDK Example

EksClient eks = EksClient.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test", "test")))
    .build();

// Create cluster
CreateClusterResponse created = eks.createCluster(r -> r
    .name("my-cluster")
    .roleArn("arn:aws:iam::000000000000:role/eks-role")
    .resourcesVpcConfig(v -> v
        .subnetIds(List.of())
        .securityGroupIds(List.of()))
    .version("1.29")
    .tags(Map.of("env", "dev")));

// Describe cluster
DescribeClusterResponse described = eks.describeCluster(r -> r
    .name("my-cluster"));

System.out.println(described.cluster().status()); // ACTIVE

// List clusters
List<String> names = eks.listClusters(r -> {}).clusters();

// Tag resource
eks.tagResource(r -> r
    .resourceArn(created.cluster().arn())
    .tags(Map.of("team", "platform")));

// Delete cluster
eks.deleteCluster(r -> r.name("my-cluster"));

Not Implemented (Phase 1)

The following EKS features are not yet supported:

Node groups (CreateNodegroup, DescribeNodegroup, ListNodegroups, DeleteNodegroup)
Fargate profiles
UpdateClusterConfig / UpdateClusterVersion
Add-ons (CreateAddon, DescribeAddon, ListAddons)
Identity provider configs
Access entries and policies
Encryption config