Light, fluffy, and always free - The AWS Local Emulator alternative
docs: add AWS Cloud Map service docs, fix service count, add analytics (#1221)
Hector Ventura446697ec714a
diff --git a/README.md b/README.mdindex 18cc8e7f34..d6d5b4553a 100644--- a/README.md+++ b/README.md@@ -177,7 +177,7 @@ LocalStack's community edition [sunset in March 2026](https://blog.localstack.cl| CodeBuild | Real Docker execution | No || Native binary | ~40 MB | No |-**52 AWS services. Broad coverage. Free forever.**+**53 AWS services. Broad coverage. Free forever.**## Architecture Overview@@ -220,10 +220,10 @@ Floci supports local emulation for application services, data services, eventing|---|---|| Core app services | S3, SQS, SNS, DynamoDB, Lambda, IAM, STS, KMS, Secrets Manager || Events and workflows | EventBridge, EventBridge Pipes, EventBridge Scheduler, Step Functions, CloudWatch Logs, CloudWatch Metrics |-| API and identity | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53 |+| API and identity | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Cloud Map || Containers and compute | ECS, EC2, EKS, CodeBuild, CodeDeploy, Auto Scaling, ELB v2 || Graph database | Neptune |-| Data and analytics | Athena, Glue, Firehose, OpenSearch, Textract |+| Data and analytics | Athena, Glue, Firehose, OpenSearch, Textract, Transcribe || Messaging and transfer | SES, SES v2, Kinesis, Transfer Family || Cost and billing | Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports || Backup and config | AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation |@@ -270,6 +270,7 @@ For operation-level compatibility, see the [Services Overview](https://floci.io/| EC2 | Real Docker | RunInstances launches containers, SSH key injection, UserData, IMDS, VPC resources || ACM | In-process | Certificate issuance and validation lifecycle || ECR | In-process with real registry | Repositories, docker push / pull, image-backed Lambda functions |+| Resource Groups Tagging API | In-process | GetResources, tag and untag resources, tag key and value discovery across services || SES | In-process | Send email, raw email, identity verification, DKIM, templates || SES v2 | In-process | REST JSON API, identities, DKIM, account sending, templates || OpenSearch | Real Docker | Domain CRUD, tags, versions, instance types, upgrade stubs |@@ -284,8 +285,10 @@ For operation-level compatibility, see the [Services Overview](https://floci.io/| AWS Backup | In-process | Vaults, backup plans, selections, simulated job lifecycle, recovery points || AWS Config | In-process | Config rules, configuration recorders, delivery channels, conformance packs, tagging || Route53 | In-process | Hosted zones, SOA and NS records, resource record sets, change tracking, tagging |+| Cloud Map | In-process | HTTP and DNS namespaces, services, instance registration, discovery queries, operations, tagging || Transfer Family | In-process | Server lifecycle, user management, SSH key import, tagging || Textract | In-process stub | API-compatible stubs, dummy block data, async job simulation |+| Transcribe | In-process stub | Transcription jobs and custom vocabularies; jobs complete immediately, no real audio processing || Pricing | In-process with static snapshot | Product discovery, attributes, price list files, pagination || Cost Explorer | In-process | Cost synthesized from Floci resource state and pricing snapshots || Cost and Usage Reports | In-process with floci-duck sidecar | CUR 2.0 and FOCUS 1.2 columns, account-scoped storage, Parquet emission |diff --git a/docs/index.md b/docs/index.mdindex 3682d752ef..90b1bf25f8 100644--- a/docs/index.md+++ b/docs/index.md@@ -12,7 +12,7 @@ Floci is a fast, free, and open-source local AWS service emulator built for deve## Supported Services-Floci emulates 52 AWS services. See the [Services Overview](services/index.md) for per-service operation counts, endpoints, and full protocol details.+Floci emulates 53 AWS services. See the [Services Overview](services/index.md) for per-service operation counts, endpoints, and full protocol details.| Service | Protocol ||---|---|@@ -36,6 +36,7 @@ Floci emulates 52 AWS services. See the [Services Overview](services/index.md) f| STS | Query || ElastiCache (Redis / Valkey) | Query + RESP proxy || RDS (PostgreSQL / MySQL) | Query + wire proxy |+| Neptune (graph DB / Gremlin) | Query + WebSocket proxy || MSK (Kafka / Redpanda) | REST JSON + Kafka || Athena | JSON 1.1 || Glue Data Catalog + Schema Registry | JSON 1.1 |@@ -44,8 +45,10 @@ Floci emulates 52 AWS services. See the [Services Overview](services/index.md) f| EC2 | EC2 Query || ACM | JSON 1.1 || ECR | JSON 1.1 + OCI Distribution |+| Resource Groups Tagging API | JSON 1.1 || OpenSearch | REST JSON || EventBridge | JSON 1.1 |+| EventBridge Pipes | REST JSON || EventBridge Scheduler | REST JSON || CloudWatch Logs & Metrics | JSON 1.1 / Query || AppConfig + AppConfigData | REST JSON |@@ -56,9 +59,12 @@ Floci emulates 52 AWS services. See the [Services Overview](services/index.md) f| CodeBuild | JSON 1.1 || CodeDeploy | JSON 1.1 || AWS Backup | REST JSON |+| CloudFront | REST XML || Route53 | REST XML |+| Cloud Map | JSON 1.1 || AWS Config | JSON 1.1 || Textract | JSON 1.1 |+| Transcribe | JSON 1.1 || Pricing | JSON 1.1 || Cost Explorer | JSON 1.1 || Cost and Usage Reports | JSON 1.1 |diff --git a/docs/services/cloudmap.md b/docs/services/cloudmap.mdnew file mode 100644index 0000000000..4cf7f2d1c7--- /dev/null+++ b/docs/services/cloudmap.md@@ -0,0 +1,120 @@+# AWS Cloud Map++**Protocol:** JSON 1.1+**Header:** `X-Amz-Target: Route53AutoNaming_v20170314.<Action>`+**Endpoint prefix:** `servicediscovery`++Floci emulates the AWS Cloud Map (service discovery) control plane in-process:+namespaces, services, and registered instances are stored as account-aware+domain objects, and discovery queries resolve against that in-memory state.++Asynchronous operations (`CreateHttpNamespace`, `CreatePublicDnsNamespace`,+`CreatePrivateDnsNamespace`, `DeleteNamespace`, `RegisterInstance`,+`DeregisterInstance`) apply their effect synchronously and return an operation+id. The operation reaches `SUCCESS` immediately by default, so a follow-up+`GetOperation` call returns a completed operation without polling. No real DNS+records or Route 53 hosted zones are created — public and private DNS+namespaces are assigned a synthetic `HostedZoneId` so SDK and CLI clients can+exercise the full Cloud Map control flow locally.++## Supported Operations++| Operation | Notes |+|-----------|-------|+| `CreateHttpNamespace` | Creates an `HTTP` namespace; returns an operation id |+| `CreatePublicDnsNamespace` | Creates a `DNS_PUBLIC` namespace with a synthetic `HostedZoneId` |+| `CreatePrivateDnsNamespace` | Creates a `DNS_PRIVATE` namespace; requires `Vpc`, assigns a `HostedZoneId` |+| `GetNamespace` | Returns a namespace by `Id` |+| `ListNamespaces` | Lists namespaces in the current region |+| `DeleteNamespace` | Deletes an empty namespace; fails with `ResourceInUse` if it still has services |+| `CreateService` | Creates a service (optionally under a namespace), tracks revision and instance count |+| `GetService` | Returns a service by `Id` |+| `ListServices` | Lists services, optionally filtered by `NamespaceId` |+| `DeleteService` | Deletes a service with no instances; fails with `ResourceInUse` otherwise |+| `RegisterInstance` | Registers an instance under a service; requires `InstanceId` and `Attributes`, bumps service revision |+| `DeregisterInstance` | Removes a registered instance and bumps service revision |+| `GetInstance` | Returns a registered instance by `ServiceId` and `InstanceId` |+| `ListInstances` | Lists instances registered under a service |+| `GetInstancesHealthStatus` | Returns health status keyed by instance id, with optional `Instances` filter |+| `DiscoverInstances` | Resolves instances by `NamespaceName` + `ServiceName`, with `HealthStatus` and `QueryParameters` filtering |+| `DiscoverInstancesRevision` | Returns the current revision for a discovered service |+| `GetOperation` | Returns an operation by `Id` |+| `ListOperations` | Lists operations with optional `STATUS`, `TYPE`, `NAMESPACE_ID`, and `SERVICE_ID` filters |+| `TagResource` | Adds tags to a namespace or service ARN |+| `UntagResource` | Removes tag keys from a namespace or service ARN |+| `ListTagsForResource` | Lists tags for a namespace or service ARN |++`DiscoverInstances` supports the `HEALTHY`, `UNHEALTHY`, `HEALTHY_OR_ELSE_ALL`,+and `ALL` health filters, and matches instances whose attributes contain every+key/value pair supplied in `QueryParameters`.++## Configuration++| Variable | Default | Description |+|---|---|---|+| `FLOCI_SERVICES_CLOUDMAP_ENABLED` | `true` | Enable or disable the service |+| `FLOCI_SERVICES_CLOUDMAP_OPERATION_COMPLETION_DELAY_SECONDS` | `0` | Delay before an async operation transitions from `PENDING` to `SUCCESS`; `0` completes immediately |++## Examples++```bash+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++aws servicediscovery create-http-namespace --name floci-demo++aws servicediscovery list-namespaces++aws servicediscovery create-service \+ --name backend \+ --namespace-id ns-xxxxxxxxxxxxxxxxxxxx++aws servicediscovery register-instance \+ --service-id srv-xxxxxxxxxxxxxxxxxxxx \+ --instance-id i-0123456789 \+ --attributes AWS_INSTANCE_IPV4=10.0.0.10++aws servicediscovery discover-instances \+ --namespace-name floci-demo \+ --service-name backend+```++```python+import boto3++client = boto3.client(+ "servicediscovery",+ endpoint_url="http://localhost:4566",+ region_name="us-east-1",+)++ns = client.create_http_namespace(Name="floci-demo")+client.get_operation(OperationId=ns["OperationId"]) # Status == "SUCCESS"++namespace_id = client.list_namespaces()["Namespaces"][0]["Id"]+service = client.create_service(Name="backend", NamespaceId=namespace_id)++client.register_instance(+ ServiceId=service["Service"]["Id"],+ InstanceId="i-0123456789",+ Attributes={"AWS_INSTANCE_IPV4": "10.0.0.10"},+)++found = client.discover_instances(NamespaceName="floci-demo", ServiceName="backend")+print(found["Instances"])+```++## Related Docs++- [Services overview](index.md)+- [Route53](route53.md)+- [AWS CLI & SDK setup](../getting-started/aws-setup.md)+- [Environment variables](../configuration/environment-variables.md)++## Out of Scope++- Real DNS resolution or Route 53 hosted zone / record set creation.+- Route 53 health checks backing `HealthCheckConfig` (custom health status is stored, not actively probed).+- Cross-region namespace and service discovery.diff --git a/docs/services/index.md b/docs/services/index.mdindex 3944b7247b..a418708b06 100644--- a/docs/services/index.md+++ b/docs/services/index.md@@ -1,6 +1,6 @@# Services Overview-Floci emulates 52 AWS services on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.+Floci emulates 53 AWS services on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.This page is the canonical reference for supported service and operation counts. Some services expose separate control-plane and data-plane rows below. Other docs (and the README) should link here rather than duplicating the table.@@ -59,6 +59,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac| [AWS Backup](backup.md) | `/backup-vaults/*`, `/backup/plans/*`, `/backup-jobs/*`, `/supported-resource-types` | REST JSON | 20 || [CloudFront](cloudfront.md) | `/2020-05-31/distribution/*`, `/2020-05-31/cache-policy/*`, `/2020-05-31/function/*` | REST XML | 50 || [Route53](route53.md) | `/2013-04-01/hostedzone/*`, `/2013-04-01/healthcheck/*`, `/2013-04-01/change/*` | REST XML | 17 |+| [Cloud Map](cloudmap.md) | `POST /` + `X-Amz-Target: Route53AutoNaming_v20170314.*` | JSON 1.1 | 22 || [AWS Config](config.md) | `POST /` + `X-Amz-Target: StarlingDoveService.*` | JSON 1.1 | 20 || [Textract](textract.md) | `POST /` + `X-Amz-Target: Textract.*` | JSON 1.1 | 6 || [Transcribe](transcribe.md) | `POST /` + `X-Amz-Target: Transcribe.*` | JSON 1.1 | 8 |diff --git a/mkdocs.yml b/mkdocs.ymlindex 9c33784ce4..197b13204c 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -7,6 +7,7 @@ edit_uri: edit/main/docs/theme:name: material+ custom_dir: overrideslogo: assets/floci-header.svgfavicon: assets/floci.svgpalette:@@ -116,8 +117,16 @@ nav:- AWS Backup: services/backup.md- CloudFront: services/cloudfront.md- Route53: services/route53.md+ - AWS Cloud Map: services/cloudmap.md- AppSync: services/appsync.md- Transfer Family: services/transfer.md+ - AWS Config: services/config.md+ - Textract: services/textract.md+ - Transcribe: services/transcribe.md+ - Pricing: services/pricing.md+ - Cost Explorer: services/ce.md+ - Cost and Usage Reports: services/cur.md+ - BCM Data Exports: services/bcm-data-exports.md- Testcontainers:- Overview: testcontainers/index.md- Java: testcontainers/java.mddiff --git a/overrides/main.html b/overrides/main.htmlnew file mode 100644index 0000000000..9b1277deaf--- /dev/null+++ b/overrides/main.html@@ -0,0 +1,6 @@+{% extends "base.html" %}++{% block extrahead %}+ {{ super() }}+ <script defer src="https://cloud.umami.is/script.js" data-website-id="b2ab8ccd-4619-4b94-bfa6-e8870961d6eb"></script>+{% endblock %}