feat: parity batch 2 (review follow-ups, CFN in-progress states, OCI LB backend TLS, ...)

.github/workflows/ci.yml

@@ -862,6 +862,34 @@ jobs:
           GOPHERSTACK_TEST_IMAGE: gopherstack:tc-local
         run: go test -count=1 -timeout 10m ./...
 
+  helm-tests:
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          token: ${{ env.GH_CI_TOKEN }}
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: go.mod
+          check-latest: true
+          cache: true
+
+      - name: Download binary
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: gopherstack-binary
+          path: bin/
+
+      - name: Lint, render and install the Helm chart on k3s
+        env:
+          GOPHERSTACK_TEST_DOCKER: "1"
+        run: |
+          chmod +x bin/gopherstack-linux
+          go test -count=1 -timeout 15m -v ./test/helm/
+
   integration:
     runs-on: ubuntu-latest
     needs: [integration-tests]

Dockerfile

@@ -32,13 +32,22 @@ RUN CGO_ENABLED=0 go build \
     -ldflags="-w -s -extldflags '-static -fno-PIC'" \
     -o gopherstack
 
-# Final stage
-FROM scratch
+# Writable state dir for the non-root runtime user (65532:65532)
+FROM --platform=$BUILDPLATFORM alpine:3.22@sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f AS state
+RUN mkdir /data
 
-WORKDIR /root/
+# Final stage: distroless static (nonroot) has a world-searchable / (containerd would unpack a bare
+# scratch / as 0700 root), plus ca-certificates, tzdata and a 1777 /tmp.
+FROM gcr.io/distroless/static:nonroot@sha256:25ac8f0c3b2334a9eb05452266bd4697864a8c8ef0ef71e5e6480d7f92868329
+
+COPY --from=state --chown=65532:65532 /data /data
+
+WORKDIR /usr/local/bin
+
+COPY --from=builder --chown=0:0 --chmod=755 /app/gopherstack .
+
+USER 65532:65532
 
-# Copy the Pre-built binary from the previous stage
-COPY --from=builder /app/gopherstack .
 
 # Expose port 8000 to the outside world
 EXPOSE 8000

Dockerfile.goreleaser

@@ -1,12 +1,21 @@
 # Dockerfile used by GoReleaser for multi-arch builds
-FROM scratch
+FROM --platform=$BUILDPLATFORM alpine:3.22@sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f AS state
+RUN mkdir /data
+
+# distroless static (nonroot): world-searchable /, ca-certificates, tzdata, 1777 /tmp, UID 65532.
+FROM gcr.io/distroless/static:nonroot@sha256:25ac8f0c3b2334a9eb05452266bd4697864a8c8ef0ef71e5e6480d7f92868329
 
 ARG TARGETPLATFORM
 
-WORKDIR /root/
+COPY --from=state --chown=65532:65532 /data /data
+
+WORKDIR /usr/local/bin
 
 # Copy the binary from GoReleaser context
-COPY $TARGETPLATFORM/gopherstack .
+COPY --chown=0:0 --chmod=755 $TARGETPLATFORM/gopherstack .
+
+USER 65532:65532
+
 
 # Expose port 8000
 EXPOSE 8000

Dockerfile.test

@@ -1,8 +1,14 @@
-# Lightweight test image — expects a pre-built static binary at bin/gopherstack-linux
-# (from `task build-linux`; this is a separate path from `task build`'s bin/gopherstack
-# so the two targets can't clobber each other — see gopherstack-gooq).
-FROM scratch
-COPY bin/gopherstack-linux /root/gopherstack
+# Lightweight test image: expects a pre-built static binary at bin/gopherstack-linux
+# (from `task build-linux`; separate from `task build`'s bin/gopherstack — see gopherstack-gooq).
+# Same non-root layout as the release image. Must build with the classic (non-BuildKit)
+# builder testcontainers uses: no $BUILDPLATFORM, no COPY --chmod (the binary is already 0755).
+FROM alpine:3.22@sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f AS state
+RUN mkdir /data
+
+FROM gcr.io/distroless/static:nonroot@sha256:25ac8f0c3b2334a9eb05452266bd4697864a8c8ef0ef71e5e6480d7f92868329
+COPY --from=state --chown=65532:65532 /data /data
+COPY --chown=0:0 bin/gopherstack-linux /usr/local/bin/gopherstack
+USER 65532:65532
 EXPOSE 8000
 EXPOSE 1883
-CMD ["/root/gopherstack"]
+CMD ["/usr/local/bin/gopherstack"]

README.md

@@ -135,6 +135,14 @@ docker compose up -d
 For Lambda support the container needs access to a container runtime — see
 [docs/docker.md](docs/docker.md).
 
+### Kubernetes (Helm)
+
+```bash
+helm install gopherstack ./charts/gopherstack
+```
+
+See [docs/kubernetes.md](docs/kubernetes.md).
+
 ### Testcontainers (Go)
 
 Gopherstack ships a reusable [Testcontainers for Go](https://golang.testcontainers.org/)
@@ -339,6 +347,7 @@ A single switch picks the default for every container-backed engine (RDS/Aurora,
 | `--transparent-ca-dir` | `TRANSPARENT_CA_DIR` | ephemeral | Directory to persist the CA so it is trusted once. |
 | `--transparent-container-ca-path` | `TRANSPARENT_CONTAINER_CA_PATH` | temp file (skipped when containerised) | CA PEM path visible to the Docker daemon; required to inject the CA when gopherstack itself runs in Docker. |
 | `--rds-engine` | `RDS_ENGINE` | `stub` | RDS engine mode: `stub` (metadata only) or `docker` (real `postgres`/`mysql`/`mariadb` container per DB instance, one per Aurora cluster; Data API stays on SQLite; `RDS_DB_HOST` overrides the advertised host, default `127.0.0.1`; ports bind loopback only unless it is non-loopback, then all interfaces; Postgres runs `postgis/postgis` + pgvector with RDS-style `aws_s3`/`aws_lambda` extensions unless `RDS_POSTGRES_EXTENSIONS=false`; `RDS_SQLSERVER_ENGINE=docker` opts `sqlserver-*` into a real SQL Server container (amd64 only; accepts the Microsoft EULA); `RDS_CALLOUT_HOST`/`RDS_CALLOUT_BIND` set the address containers dial / the callout listener binds (default: container bridge gateway, never a wildcard)). |
+| `--dsql-engine` | `DSQL_ENGINE` | `stub` | Aurora DSQL engine mode: `stub` (control plane only) or `docker` (one `postgres` container per cluster behind a TLS proxy that accepts `GenerateDbConnectAuthToken` / `GenerateDBConnectAdminAuthToken` tokens as the password for user `admin`; `CREATE INDEX ASYNC`, `sys.jobs`, `sys.wait_for_job`; connect address at `/_gopherstack/dsql/clusters/{id}`, CA at `/_gopherstack/dsql/ca.pem`; `DSQL_ENGINE_IMAGE` picks the image, default `postgres:17`). |
 | `--docdb-engine` | `DOCDB_ENGINE` | `stub` | DocumentDB engine mode: `stub` (metadata only) or `docker` (one plaintext `mongo` container per cluster, `mongo:4.4` for 3.6/4.0 and `mongo:5.0` for 5.0; `DOCDB_HOST` overrides the advertised host, default `127.0.0.1`; ports bind loopback only unless it is non-loopback, then all interfaces). |
 | `--redshift-engine` | `REDSHIFT_ENGINE` | `stub` | Redshift engine mode: `stub` (metadata only) or `docker` (one `postgres:17` container per provisioned cluster with MasterUsername/MasterUserPassword/DBName; Endpoint reports the published `127.0.0.1` port and the Redshift Data API runs SQL against it; `REDSHIFT_HOST` overrides the advertised host; Serverless workgroups stay metadata-only). |
 | `--neptune-engine` | `NEPTUNE_ENGINE` | `stub` | Neptune engine mode: `stub` (metadata only), `embedded` (in-process Gremlin, openCypher and Bolt over one persisted property graph; no container runtime) or `docker` (the same in-process graph by default; `NEPTUNE_GREMLIN=container` runs one `tinkerpop/gremlin-server` container per cluster instead, TinkerPop 3.4.13 for engine 1.0/1.1, 3.5.7 for 1.2, 3.6.8 for 1.3, 3.7.3 later). Endpoint, ReaderEndpoint, Port and member instances report the published `127.0.0.1` port, Gremlin over WebSocket/HTTP at `/gremlin`; `NEPTUNE_HOST` overrides the advertised host; no IAM auth. |
@@ -890,7 +899,7 @@ Every service links to its own page with a coverage breakdown — audited operat
 | [SageMaker](services/sagemaker/README.md) | A | 70 | 1 gap; 19 structural gaps |
 | [SageMaker Runtime](services/sagemakerruntime/README.md) | A | 3 | 1 gap; 1 structural gap |
 | [Textract](services/textract/README.md) | A | 25 | 2 structural gaps; 1 deferred |
-| [Transcribe](services/transcribe/README.md) | A | 44 | 2 structural gaps |
+| [Transcribe](services/transcribe/README.md) | A | 44 | 6 gaps; 2 structural gaps |
 | [Translate](services/translate/README.md) | A | 19 | 1 gap; 2 structural gaps |
 
 ### Media
@@ -969,7 +978,7 @@ Every service links to its own page with a coverage breakdown — audited operat
 | [Google Cloud KMS](services/gcpkms/README.md) | B | 35 | 4 gaps |
 | [Google Cloud Pub/Sub](services/gcppubsub/README.md) | B | 38 | 6 gaps |
 | [Google Cloud Resource Manager and Service Usage](services/gcpresourcemanager/README.md) | B | 39 | 9 gaps |
-| [Google Cloud Storage](services/gcpstorage/README.md) | B | 28 | 8 gaps |
+| [Google Cloud Storage](services/gcpstorage/README.md) | B | 37 | 9 gaps |
 | [Google Secret Manager](services/gcpsecretmanager/README.md) | B | 18 | 5 gaps |
 | [Identity Platform](services/gcpidentitytoolkit/README.md) | B | 1 | 6 gaps |
 | [Kubernetes Engine](services/gcpcontainer/README.md) | B | — | 5 families; 5 gaps |
@@ -982,10 +991,13 @@ Every service links to its own page with a coverage breakdown — audited operat
 |---|---|---|---|
 | [OCI API Gateway](services/ociapigateway/README.md) | B | 22 | 10 gaps |
 | [OCI Artifacts and Container Registry](services/ociartifacts/README.md) | B | 37 | 7 gaps |
+| [OCI Autonomous Database](services/ocidatabase/README.md) | B | 21 | 7 gaps |
 | [OCI Container Engine for Kubernetes](services/ocicontainerengine/README.md) | B | 20 | 9 gaps |
 | [OCI Container Instances](services/ocicontainerinstances/README.md) | B | 18 | 7 gaps |
 | [OCI Core Services](services/ocicore/README.md) | B | 135 | 11 gaps |
+| [OCI DNS](services/ocidns/README.md) | B | 52 | 7 gaps |
 | [OCI Events](services/ocievents/README.md) | B | 6 | 6 gaps |
+| [OCI File Storage](services/ocifilestorage/README.md) | B | 74 | 7 gaps |
 | [OCI Functions](services/ocifunctions/README.md) | B | 16 | 9 gaps |
 | [OCI Identity](services/ociidentity/README.md) | B | 70 | 9 gaps |
 | [OCI Load Balancer](services/ociloadbalancer/README.md) | B | 61 | 9 gaps |
@@ -1006,7 +1018,7 @@ Every service links to its own page with a coverage breakdown — audited operat
 | [Amp](services/amp/README.md) | B | 44 | 9 gaps; 2 structural gaps |
 | [AppStream 2.0](services/appstream/README.md) | A | 44 | 5 structural gaps |
 | [Appintegrations](services/appintegrations/README.md) | B | 23 | 3 gaps; 1 structural gap |
-| [Azurearm](services/azurearm/README.md) | B | 20 | 69 gaps; 3 deferred |
+| [Azurearm](services/azurearm/README.md) | B | 20 | 73 gaps; 3 deferred |
 | [Azurestoragevhost](services/azurestoragevhost/README.md) | B | 2 | 2 gaps; 1 deferred |
 | [Bcmdataexports](services/bcmdataexports/README.md) | B | 12 | 6 gaps |
 | [Bedrockagentcore](services/bedrockagentcore/README.md) | B | 30 | 11 gaps; 2 structural gaps |
@@ -1018,13 +1030,14 @@ Every service links to its own page with a coverage breakdown — audited operat
 | [Connect](services/connect/README.md) | B | 312 | 21 gaps; 2 structural gaps |
 | [Cur](services/cur/README.md) | B | 7 | 6 gaps |
 | [Directconnect](services/directconnect/README.md) | A | 73 | 2 gaps; 8 structural gaps; 1 deferred |
-| [Dsql](services/dsql/README.md) | A | 16 | 3 structural gaps |
+| [Dsql](services/dsql/README.md) | A | 16 | 8 gaps; 2 structural gaps |
 | [Ecrpublic](services/ecrpublic/README.md) | A | 23 | 3 structural gaps |
 | [Globalaccelerator](services/globalaccelerator/README.md) | B | 56 | 4 gaps; 2 structural gaps |
 | [Grafana](services/grafana/README.md) | A | 25 | 1 structural gap |
 | [HealthOmics](services/omics/README.md) | A | — | 25 families; 5 structural gaps; 1 deferred |
 | [Kafkaconnect](services/kafkaconnect/README.md) | A | 19 | 3 gaps; 3 structural gaps |
 | [Kinesisvideo](services/kinesisvideo/README.md) | A | 32 | 3 structural gaps |
+| [Lambdaweb](services/lambdaweb/README.md) | B | 20 | 11 gaps; 1 structural gap |
 | [Lightsail](services/lightsail/README.md) | A | — | 29 families; 1 gap; 6 structural gaps; 2 deferred |
 | [Managed Blockchain](services/managedblockchain/README.md) | A | 27 | 3 structural gaps |
 | [Marketplaceentitlementservice](services/marketplaceentitlementservice/README.md) | B | 1 | 3 gaps; 1 structural gap |
@@ -1148,6 +1161,7 @@ cdk deploy
 
 - [Quickstart](docs/quickstart.md)
 - [Running with Docker](docs/docker.md)
+- [Running on Kubernetes (Helm)](docs/kubernetes.md)
 - [Security group enforcement](docs/security-groups.md)
 - [Migrating from LocalStack](docs/migration.md)
 - [Architecture](docs/architecture/README.md)

Taskfile.yml

@@ -165,6 +165,21 @@ tasks:
           -ldflags "-w -s -X {{.VERSION_PKG}}.Build={{.BUILD_VERSION}}" \
           -o bin/{{.BINARY_NAME}}-linux .
 
+  helm-test:
+    desc: Lint and golden-render charts/gopherstack with the pinned helm image (needs docker)
+    env:
+      GOPHERSTACK_TEST_DOCKER: "1"
+    cmds:
+      - go test -count=1 -run 'TestChart_(Lint|GoldenTemplate|SchemaRejects)' ./test/helm/
+
+  helm-install-test:
+    desc: Install charts/gopherstack into a k3s cluster and call it (needs docker)
+    deps: [build-linux]
+    env:
+      GOPHERSTACK_TEST_DOCKER: "1"
+    cmds:
+      - go test -count=1 -timeout 15m -run TestChart_InstallK3s -v ./test/helm/
+
   install-deps:
     desc: Install pinned golangci-lint, fieldalignment and dev MCP CLIs
     run: once

charts/gopherstack/.helmignore

@@ -0,0 +1,4 @@
+.git
+*.swp
+*.bak
+*.tmp

charts/gopherstack/Chart.yaml

@@ -0,0 +1,15 @@
+apiVersion: v2
+name: gopherstack
+description: Gopherstack, a local multi-cloud (AWS, Azure, GCP, OCI) service emulator
+type: application
+version: 0.1.0
+appVersion: "1.9.1"
+kubeVersion: ">=1.25.0-0"
+home: https://github.com/blackbirdworks/gopherstack
+sources:
+  - https://github.com/blackbirdworks/gopherstack
+keywords:
+  - aws
+  - emulator
+  - localstack
+  - testing

charts/gopherstack/templates/NOTES.txt

@@ -0,0 +1,29 @@
+Gopherstack {{ .Chart.AppVersion }} is deploying as {{ include "gopherstack.fullname" . }}.
+
+Point AWS SDKs and the CLI at the service:
+{{- if .Values.ingress.enabled }}
+{{- range .Values.ingress.hosts }}
+  export AWS_ENDPOINT_URL=http{{ if $.Values.ingress.tls }}s{{ end }}://{{ .host }}
+{{- end }}
+{{- else if eq .Values.service.type "NodePort" }}
+  export NODE_PORT=$(kubectl get svc {{ include "gopherstack.fullname" . }} -n {{ .Release.Namespace }} -o jsonpath='{.spec.ports[0].nodePort}')
+  export AWS_ENDPOINT_URL=http://<node-address>:$NODE_PORT
+{{- else if eq .Values.service.type "LoadBalancer" }}
+  export AWS_ENDPOINT_URL=http://$(kubectl get svc {{ include "gopherstack.fullname" . }} -n {{ .Release.Namespace }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}'):{{ .Values.service.port }}
+{{- else }}
+  kubectl port-forward -n {{ .Release.Namespace }} svc/{{ include "gopherstack.fullname" . }} {{ .Values.service.port }}:{{ .Values.service.port }}
+  export AWS_ENDPOINT_URL=http://localhost:{{ .Values.service.port }}
+{{- end }}
+  export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION={{ .Values.config.region }}
+
+In-cluster endpoint: http://{{ include "gopherstack.fullname" . }}.{{ .Release.Namespace }}.svc.cluster.local:{{ .Values.service.port }}
+Health: {{ .Values.probes.path }}
+{{- if not .Values.persistence.enabled }}
+
+State is in memory and is lost when the pod restarts. Set persistence.enabled=true to keep it.
+{{- end }}
+{{- if not .Values.dind.enabled }}
+
+Docker-backed engines (RDS, EKS, Lambda containers, ...) need a container runtime and run
+as stubs in this pod. Set dind.enabled=true and config.engines=docker to use a DinD sidecar.
+{{- end }}

charts/gopherstack/templates/_helpers.tpl

@@ -0,0 +1,48 @@
+{{- define "gopherstack.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "gopherstack.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "gopherstack.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "gopherstack.labels" -}}
+helm.sh/chart: {{ include "gopherstack.chart" . }}
+{{ include "gopherstack.selectorLabels" . }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{- define "gopherstack.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "gopherstack.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{- define "gopherstack.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+{{- default (include "gopherstack.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+{{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "gopherstack.image" -}}
+{{- printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) -}}
+{{- end -}}
+
+{{- define "gopherstack.pvcName" -}}
+{{- default (include "gopherstack.fullname" .) .Values.persistence.existingClaim -}}
+{{- end -}}