Skip to content

Distribution & Updates

PII Eraser is distributed as a fully self-contained container image. Updating your deployment is as simple as pulling the latest image from your registry and triggering a rolling restart of your containers.

This page explains how PII Eraser versions are tagged, how detection models are distributed, and best practices for upgrading your production environment safely.

The Container Model

Unlike cloud APIs where models change silently behind the scenes, or traditional software that requires reaching out to external license servers to download model weights, everything PII Eraser needs is packaged directly inside the container image. This architectural choice provides significant benefits for enterprise environments:

  • Air-Gapped by Design: Because the models are baked into the container at build time, PII Eraser never needs to reach out to the internet to download updates or models.
  • Absolute Reproducibility: A specific container tag (e.g., 1.2.3) will always produce the exact same detection results, forever.
  • Simplified Security Audits: Your security team only needs to scan and approve a single artifact—the container image itself.
  • Instant Rollbacks: If an update causes issues in your pipeline, rolling back is as simple as reverting to the previous image tag.

Versioning & Image Tags

PII Eraser follows standard Semantic Versioning (MAJOR.MINOR.PATCH).

  • MAJOR: Breaking changes to the REST API schema or config.yaml parameters.
  • MINOR: New features, new entity types, new languages, and model updates. Fully backwards-compatible.
  • PATCH: Bug fixes, performance optimizations, and security patches. Fully backwards-compatible.

We publish multiple container image tags for every release, allowing you to choose the right balance between stability and automatic updates for your environment.

Tag Pattern Resolves To Use Case
latest The absolute newest stable release Development and evaluation only. Not recommended for production.
1 The newest 1.x.y release Opt into all new features, models, and patches automatically.
1.2 The newest 1.2.y release Recommended for production. Automatically receive security patches, but protect against unexpected model behavior changes.
1.2.3 The exact, specific release For environments with strict regulatory requirements where detection output must remain bit-for-bit stable.

Evaluating Model Updates (Minor Versions)

Because new models and entity types are delivered via MINOR version updates, upgrading from 1.1 to 1.2 may change exactly which entities are detected in your text (typically improving accuracy and recall). If your downstream pipeline relies on rigid output formatting, we highly recommend testing minor version upgrades in a staging environment first.

Upgrade Guidance

Because PII Eraser is completely stateless, you can achieve zero-downtime upgrades by utilizing your orchestrator's rolling deployment features (e.g., Kubernetes RollingUpdates or AWS ECS deployment circuits).

When you are ready to upgrade, follow this standard checklist:

  1. Review the Changelog: Check the GitHub Releases page for the version you are moving to. Pay special attention to any new entity types or config.yaml options.
  2. Pull the Image: If you are mirroring PII Eraser in a private enterprise registry (e.g., AWS ECR or Azure ACR), pull the new target tag and push it to your internal registry.
  3. Test in Staging: Deploy the new container tag to your pre-production environment. Run a sample of your own organization's text data through the API to ensure the new models perform as expected.
  4. Update Configuration (If necessary): If you are adopting new features, update your config.yaml or environment variables.
  5. Roll Out: Update your orchestrator's task definition or pod specification with the new image tag and initiate the deployment.

AWS CloudFormation Example

See PII Eraser's AWS CloudFormation reference implementation for an example of how to execute a rolling update.

Handling Major Version Upgrades

Major version upgrades (e.g., moving from 1.x to 2.x) indicate a breaking change in the API or configuration schema. We keep major version bumps infrequent.

When a major release occurs, we provide a deprecation window of at least 6 months for the previous major version, during which it will continue to receive critical security patches (PATCH updates). This ensures your team has ample time to review the migration guide, update your API integration code, and test the new major version before upgrading.