Other Platforms

This guide provides deployment guidelines for Kubernetes, Azure Container Instances, and other container orchestration platforms. PII Eraser is a standard OCI container with no platform-specific dependencies — if your orchestrator can run a Docker container, it can run PII Eraser.

For AWS-specific deployments with ECS, see the dedicated AWS Deployment guide, which provides a complete CloudFormation reference implementation.

General Deployment Guidelines

Regardless of your orchestration platform, the following guidelines apply to all PII Eraser deployments.

Networking & Load Balancing

PII Eraser is designed to operate behind a load balancer or API gateway:

• No Built-In TLS: PII Eraser serves plain HTTP on port 8000. Terminate TLS at your load balancer, ingress controller, or API gateway.
• No Built-In CORS: If your frontend clients need to call PII Eraser directly from a browser, configure CORS headers at your reverse proxy or API gateway layer.
• Internal-Only Access: PII Eraser should not be exposed to the public internet. Deploy it in a private subnet or internal network segment, accessible only from your application layer.
• High Request Timeouts: PII Eraser supports inputs up to 1 million tokens. For very large inputs, ensure your load balancer's idle timeout is set high enough to avoid premature connection termination (the AWS reference implementation defaults to 600 seconds).

Health Check

PII Eraser provides three health check mechanisms. Use whichever is best supported by your platform.

Option 1: HTTP Health Check

Configure your orchestrator to probe the /health endpoint. Best for K8s, ALB target groups or anything that supports HTTP checks natively. Recommended parameters:

Parameter	Value
Interval	10 seconds
Timeout	5 seconds
Healthy Threshold	2 consecutive successes
Unhealthy Threshold	3 consecutive failures
Start Period / Initial Delay	120 seconds

The 120-second start period accounts for model loading at startup. Adjust upward if running on slower hardware.

Option 2: Exec-Based Health Check

For platforms that support running a command inside the container such as ECS task definitions and K8s exec probes, PII Eraser includes a lightweight health check script:

/venv/bin/python /app/healthcheck.py

The script calls the /health endpoint internally and exits with code 0 (healthy) or 1 (unhealthy).

Here is an example from the AWS reference implementation:

HealthCheck:
  Command: ["CMD", "/venv/bin/python", "/app/healthcheck.py"]
  Interval: 10
  Timeout: 5
  Retries: 3
  StartPeriod: 120

Option 3: Built-in Docker HEALTHCHECK

The container also has a built-in Docker HEALTHCHECK instruction which is used when running with Docker. It also uses the health check script:

HEALTHCHECK --interval=10s --timeout=5s --retries=3 --start-period=120s \
    CMD ["/venv/bin/python", "/app/healthcheck.py"]

Configuration Injection

PII Eraser can be configured via a config.yaml file or the CONFIG_B64 environment variable. Choose the method that best fits your platform:

Method	How	Best For
Volume Mount	Mount a file to /app/config.yaml inside the container.	Kubernetes ConfigMaps, Docker bind mounts, any platform with file mount support.
Environment Variable	Set CONFIG_B64 to the Base64-encoded contents of your config file.	Platforms where environment variables are easier to manage (e.g., ECS task definitions, Azure Container Instances).

Please visit the Customization Guide for more details.

Security Checklist

Apply the following hardening measures on every platform. See Security for the full rationale behind each.

Measure	How to Apply
Read-only root filesystem	Set readOnlyRootFilesystem: true (K8s) or --read-only (Docker). Mount a writable tmpfs or emptyDir at /tmp.
Drop all Linux capabilities	Set drop: ["ALL"] under securityContext.capabilities (K8s) or --cap-drop ALL (Docker).
Non-root user	PII Eraser runs as nonroot (UID 65532) by default. Enforce this with runAsNonRoot: true (K8s) or verify with your platform's user policy.
No privilege escalation	Set allowPrivilegeEscalation: false (K8s) or --security-opt no-new-privileges (Docker).
Private networking	Deploy in a private subnet or namespace. Do not assign a public IP to the container.
Restrict egress	If running a marketplace build, allow outbound HTTPS (TCP 443) only. If running fully airgapped, block all egress.

Resource Isolation

PII Eraser's inference engine is optimized for dedicated CPU access, making extensive use of CPU caches, memory bandwidth, and vector instruction pipelines. Co-locating PII Eraser with other workloads or running multiple PII Eraser containers on the same host will significantly degrade throughput due to cache thrashing and resource contention.

Follow these guidelines on every platform:

• One container per host. Do not run multiple PII Eraser instances on the same machine. Scale horizontally by adding more machines behind a load balancer.
• No noisy neighbors. Avoid scheduling other CPU-intensive workloads (databases, ML models, application servers) on the same host as PII Eraser.
• Pin CPUs if sharing is unavoidable. If co-location cannot be avoided, assign PII Eraser exclusive access to a set of CPU cores using your platform's affinity mechanism:
  • Docker: --cpuset-cpus (e.g., --cpuset-cpus="0-3")
  • Kubernetes: Set CPU requests equal to limits to obtain the Guaranteed QoS class, which provides consistent CPU time. For hard core pinning, use the CPU Manager static policy.
  • ECS (EC2): Use the distinctInstance placement constraint as shown in the reference implementation.
  • Linux (bare metal): Use taskset or cgroup cpuset to pin the container process to specific cores.

Scaling

PII Eraser is a stateless, CPU-bound workload. The recommended scaling strategy is:

• Metric: Scale on average CPU utilization.
• Target: 70% average CPU utilization is a good starting point, balancing throughput and latency headroom. If latency isn't a concern, e.g. offline batch processing, set a higher target.
• Horizontal scaling: Add more container instances behind a load balancer. Each instance processes requests independently. Ensure each instance runs on its own dedicated host (see Resource Isolation above).
• Instance sizing: For most workloads, multiple smaller instances (e.g., 4-8 vCPUs each) behind a load balancer are more cost-effective than fewer large instances. See Benchmarks & Hardware Selection for guidance.

Kubernetes

This section provides a reference Kubernetes manifest for deploying PII Eraser. Adapt it to your cluster's conventions (namespaces, ingress controllers, etc.).

ConfigMap for Configuration

Create a ConfigMap containing your config.yaml. The Deployment manifest below mounts it into the container at /app/config.yaml.

apiVersion: v1
kind: ConfigMap
metadata:
  name: pii-eraser-config
data:
  config.yaml: |
    operator: redact
    entity_types:
      - NAME
      - EMAIL
      - PHONE
      - ADDRESS

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pii-eraser
  labels:
    app: pii-eraser
spec:
  replicas: 2
  selector:
    matchLabels:
      app: pii-eraser
  template:
    metadata:
      labels:
        app: pii-eraser
    spec:
      # Enforce one PII Eraser pod per node to avoid CPU contention.
      # This mirrors the distinctInstance constraint in the AWS reference implementation.
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: pii-eraser
              topologyKey: kubernetes.io/hostname
      containers:
        - name: pii-eraser
          image: <your-registry>/pii-eraser:latest
          ports:
            - containerPort: 8000
          resources:
            requests:
              cpu: "4"
              memory: "7Gi"
            limits:
              cpu: "4"
              memory: "8Gi"
          securityContext:
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
            runAsNonRoot: true
            capabilities:
              drop:
                - ALL
          volumeMounts:
            - name: config
              mountPath: /app/config.yaml
              subPath: config.yaml
              readOnly: true
            - name: tmp
              mountPath: /tmp
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 120
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 120
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
      volumes:
        - name: config
          configMap:
            name: pii-eraser-config
        - name: tmp
          emptyDir:
            medium: Memory

CPU Resources & Guaranteed QoS

Setting CPU requests equal to limits (as shown above) assigns the Pod the Guaranteed QoS class in Kubernetes, which provides more consistent CPU time and reduces scheduling interference from other workloads. This is important for PII Eraser's inference performance. See Resource Isolation for details.

Service

apiVersion: v1
kind: Service
metadata:
  name: pii-eraser
spec:
  type: ClusterIP
  selector:
    app: pii-eraser
  ports:
    - port: 8000
      targetPort: 8000
      protocol: TCP

Horizontal Pod Autoscaler

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: pii-eraser
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: pii-eraser
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Topology Spread & Instance Isolation

The podAntiAffinity rule in the Deployment above enforces one PII Eraser pod per node, which is critical for performance (see Resource Isolation). For high availability across failure domains, add topologySpreadConstraints to distribute pods across availability zones. This mirrors the spread and distinctInstance placement strategies used in the AWS reference implementation.

Azure Container Instances

For quick Azure deployments, PII Eraser can be run as an Azure Container Instance (ACI). Because PII Eraser is CPU-only, it works on ACI without any GPU provisioning or driver configuration:

az container create \
  --resource-group <your-resource-group> \
  --name pii-eraser \
  --image <your-registry>/pii-eraser:latest \
  --cpu 4 \
  --memory 8 \
  --ports 8000 \
  --ip-address Private \
  --restart-policy Always \
  --secure-environment-variables CONFIG_B64="<base64-encoded-config>"

ACI does not support readOnlyRootFilesystem or capability dropping. For environments requiring full container hardening, deploy on AKS using the Kubernetes manifests above.