Data Residency

Data residency controls ensure that authentication decisions, policy evaluations, audit events, and telemetry are processed and stored within a designated geographic region. CoreSDK provides environment-variable configuration, per-tenant region pinning, and full on-premise isolation for organisations with strict data sovereignty obligations.

Phase note. Data residency controls are a Phase 3 enterprise feature. Per-tenant region pinning and the on-premise control plane require the Enterprise plan. Basic region configuration via CORESDK_DATA_REGION and local-only mode are available in all plans from Phase 1b.

Why data residency matters

Several regulatory frameworks impose strict rules on where personal data may be processed and stored:

CoreSDK's data residency controls address the technical layer of these requirements. Organisational controls — Data Processing Agreements, transfer impact assessments, and DPIAs — remain the responsibility of your compliance programme.

CORESDK_DATA_REGION

Set the CORESDK_DATA_REGION environment variable to declare the region in which the sidecar is running. CoreSDK uses this value to:

• Label all outbound OTEL spans and metrics with a data.region attribute.
• Enforce that audit sink configuration targets storage in the declared region.
• Refuse to start if a misconfigured sink would write audit data outside the declared region (when data_residency.strict: true is set).

# coresdk.yaml
data_residency:
  region: eu-west-1          # must match CORESDK_DATA_REGION
  strict: true               # refuse to start if sink region does not match

export CORESDK_DATA_REGION=eu-west-1

Supported region identifiers follow AWS region naming (eu-west-1, me-central-1, us-east-1, etc.) and map to equivalent Azure and GCP region codes when using those cloud sinks.

Pinning processing to a region

For a single-region deployment, configure the sidecar to use only local policy evaluation and a region-scoped audit sink. No data will leave the host environment unless you explicitly configure an external sink.

# coresdk.yaml — EU deployment (GDPR-compliant)
data_residency:
  region: eu-west-1
  strict: true

policy:
  source: local
  path: "/etc/coresdk/policies"
  sync_enabled: false          # no outbound policy fetch to control plane

audit:
  enabled: true
  sink: s3
  s3:
    bucket: "my-eu-audit-logs"
    region: "eu-west-1"        # data stays within the EEA
    sse_algorithm: "aws:kms"
    kms_key_id: "arn:aws:kms:eu-west-1:123456789012:key/mrk-..."

telemetry:
  otel:
    endpoint: "http://otel-collector.internal:4317"  # collector is in-region
    cross_region_export: false   # block any exporter that resolves outside the declared region

With policy.source: local and sync_enabled: false, CoreSDK operates entirely within the host environment. No policy data, JWT claims, request metadata, or audit events are transmitted outside the process boundary. This configuration is also compatible with air-gapped deployments.

UAE PDPL configuration

The UAE Personal Data Protection Law (PDPL) requires that personal data of UAE residents be processed within the UAE unless the data subject has consented to transfer or the transfer meets one of the enumerated exceptions. Use the me-central-1 (UAE) region with in-country storage:

# coresdk.yaml — UAE PDPL deployment
data_residency:
  region: me-central-1
  strict: true
  regulations:
    - uae-pdpl          # enables PDPL-specific audit event annotations

audit:
  enabled: true
  sink: s3
  s3:
    bucket: "my-uae-audit-logs"
    region: "me-central-1"
    sse_algorithm: "aws:kms"
    kms_key_id: "arn:aws:kms:me-central-1:123456789012:key/mrk-..."

The regulations list adds structured metadata to audit events — for example, regulation: uae-pdpl and data_subject_jurisdiction: ae — which simplifies evidence collection during regulatory inspections.

Per-tenant region pinning

In multi-tenant deployments, different tenants may have different data residency obligations. CoreSDK supports per-tenant region configuration so that a single sidecar deployment can serve tenants across jurisdictions without cross-region data leakage.

# coresdk.yaml — multi-tenant with per-tenant region pinning
multi_tenancy:
  enabled: true
  tenants:
    - id: "tenant-eu-001"
      data_region: eu-west-1
      audit_sink: "s3://eu-audit-logs/tenant-eu-001/"
    - id: "tenant-uae-002"
      data_region: me-central-1
      audit_sink: "s3://uae-audit-logs/tenant-uae-002/"
    - id: "tenant-us-003"
      data_region: us-east-1
      audit_sink: "s3://us-audit-logs/tenant-us-003/"

At runtime, CoreSDK reads the tenant ID from the verified JWT (tenant_id claim by default, configurable via multi_tenancy.tenant_claim). The matching tenant configuration determines:

• Which regional audit sink receives the event.
• Which data.region label is attached to OTEL spans for that request.
• Whether the request is allowed to proceed if the tenant's declared region does not match the sidecar's own data_residency.region.

If a tenant's declared region does not match the sidecar's region and data_residency.strict is true, the request is rejected with a 403 and a data_region_mismatch problem detail. This ensures tenants are never inadvertently routed to a sidecar outside their jurisdiction.

No cross-region telemetry leakage

By default, CoreSDK does not export telemetry (traces, metrics, logs) to any endpoint outside the declared region. The OTEL exporter validates the resolved IP address of the configured endpoint against the declared region's CIDR ranges before sending.

To disable this check (for example, in development environments where the collector is not co-located):

telemetry:
  otel:
    cross_region_export: false   # default: true in production mode

Span attributes that could contain personal data — request paths, user IDs, JWT claims — pass through the PII masking SpanProcessor before reaching the exporter. See PII Masking for details.

On-premise control plane for full isolation

For organisations that require complete data isolation — no outbound connections of any kind — CoreSDK supports a fully on-premise control plane deployment. In this mode:

• The control plane API runs inside your network.
• Policy bundles are distributed from your internal bundle server.
• JWK sets are fetched from your internal JWKS endpoint.
• Audit events are written to your internal storage only.
• No CoreSDK Cloud endpoints are contacted.

# coresdk.yaml — full on-premise isolation
control_plane:
  mode: self-hosted
  endpoint: "https://coresdk-cp.internal"
  ca_cert: "/etc/coresdk/tls/internal-ca.pem"

policy:
  source: bundle
  bundle_url: "https://bundle-server.internal/policies/latest.tar.gz"
  sync_enabled: true
  sync_interval_seconds: 300

auth:
  jwks_url: "https://idp.internal/.well-known/jwks.json"

audit:
  enabled: true
  sink: s3
  s3:
    endpoint: "https://minio.internal"        # on-premise S3-compatible storage
    bucket: "coresdk-audit"
    region: "us-east-1"                       # logical region label only
    path_style: true

telemetry:
  otel:
    endpoint: "http://otel-collector.internal:4317"
    cross_region_export: false

See Self-Hosted Deployment for Helm chart installation and the full on-premise architecture diagram.

Helm chart region overrides

When deploying the CoreSDK sidecar via the official Helm chart, override region configuration using values.yaml:

# values.yaml
coresdk:
  dataResidency:
    region: eu-west-1
    strict: true
    regulations:
      - gdpr

  audit:
    sink: s3
    s3:
      bucket: my-eu-audit-logs
      region: eu-west-1
      sseAlgorithm: aws:kms
      kmsKeyId: arn:aws:kms:eu-west-1:123456789012:key/mrk-...

  telemetry:
    otel:
      endpoint: http://otel-collector.eu.internal:4317
      crossRegionExport: false

Install with:

helm install coresdk oci://registry.coresdk.dev/charts/coresdk-sidecar \
  --namespace coresdk \
  --values values.yaml

The chart sets CORESDK_DATA_REGION from coresdk.dataResidency.region automatically. No manual environment variable injection is required.

Verifying residency at runtime

Use the CoreSDK CLI to confirm that the running sidecar is operating within its declared region:

core residency status

Output:

Sidecar data region:    eu-west-1
Audit sink region:      eu-west-1  [OK]
OTEL endpoint region:   eu-west-1  [OK]
Policy source:          local      [no outbound sync]
Cross-region export:    disabled   [OK]
Strict mode:            enabled

If any component is misconfigured — for example, an audit sink in a different region — the command exits non-zero and lists the violations. In strict mode, the sidecar will also refuse to start with the same error.

What is not covered

Data residency configuration addresses the technical routing layer. A complete data sovereignty programme also requires:

• GDPR Chapter V transfers: Standard Contractual Clauses or Binding Corporate Rules for any processor relationship, plus a Transfer Impact Assessment for transfers to third countries.
• UAE PDPL: Consent records or documented transfer exceptions maintained by your data controller.
• Data mapping: A record of processing activities (GDPR Art. 30) covering all systems that interact with CoreSDK, not only CoreSDK itself.
• Breach notification: Procedures for notifying supervisory authorities within the timeframe required by each applicable regulation.

CoreSDK's Phase 3 roadmap includes Data Processing Agreement templates and a GDPR Art. 30 record export that populates from audit event metadata.

Next steps

• Compliance Controls — SOC 2, HIPAA, GDPR, and PCI DSS control mapping
• Self-Hosted Deployment — on-premise control plane installation
• Air-Gapped Deployments — fully disconnected environments
• Multi-Tenancy — per-tenant configuration and isolation