Implementing EC Encoding Policy

Owned by Rumena Zlatkova (Deactivated)
Last updated: Dec 18, 2023 by Bala Harish A(AC)
5 min read

  Context-level policies can be created to manage EC (erasure coding) across the cluster. Swarm ships with cluster-level EC encoding unspecified. Unless EC is specified at the object level, every object is fully replicated, regardless of size. 

Set custom EC policies for the encoding (k:p) and the object size minimums applicable to specific domains and buckets (contexts). Context-level policies allow building a wide range of erasure-coding controls to meet business needs:

  • Disable EC on a bucket, forcing it to perform full replication on every object

  • Quadruple the object size triggers erasure coding in a special-use bucket

  • Set different EC encodings for named versus unnamed objects in a specific domain

  • Lock the domain policy as "unspecified" to cancel any policies bucket owners may have set, forcing them to accept the current cluster policy

  • Lock the cluster policy as "disabled" to stop all erasure coding, voiding any query argument or lifepoint encodings passed in with the request

It is necessary to understand how Swarm chooses among different encoding (k:p) to design EC policies because Swarm allows specifying them at multiple levels simultaneously. Encoding specified at the object level wins over any held by the context; the context policy evaluation can disable the encoding requested at the object level:

An individual object can specify EC encoding in the lifepoint header, as reps=k:p. Add a query argument, as encoding=k:p to override the lifepoint on an SCSP POST or PUT method. Adding the optional erasurecoded argument overrides the active policy.ecMinStreamSize requirement, but it cannot override an EC policy evaluating to "Disabled".

See Lifepoint Metadata Headers for setting lifepoints with erasure coding.

See SCSP Query Arguments  for using erasure coding query arguments.

Options for Specifying EC Encoding

A different EC encoding policy can be defined at the cluster and each context (domain and bucket) level, using this 2-part setting:

Part

Scope

Value (String)

Notes

Example

Part

Scope

Value (String)

Notes

Example

Encoding

Affects the current context level.

Returns 400 Bad request if value is missing or out of
range

unspecified
(default)

Allows erasure coding at this level and below, using the available policy or cluster defaults.

unspecified

disabled

Disables erasure coding at current level.

disabled

k:p

{data segments}:
{parity segments}

The specific EC encoding to use at this level.
Requirements:

Subject to the resolved policy's eCMinStreamSize
value unless it is overridden by the erasurecoded argument.

7:3

Lock (Optional)

Affects any contexts below
the current context.

anchored

Applies this encoding to all levels below, overriding any lower-level policies.

disabled anchored

7:3 anchored

EC encoding is subject to policy resolution on each write request, evaluating the object-level encoding with the context. For contexts, Swarm uses the policy at the given level unless a level above it is anchored. Swarm uses the anchored encoding.

Tip

The "anchored" lock exists to allows suppressing any policies added by domain or bucket owners below.

Anchoring allows enforcing these two situations:

Disable erasure-coding cluster-wide
policy.ecEncoding = disabled anchored
Require objects to specify encoding, regardless of context:
policy.ecEncoding = unspecified anchored

How Swarm Resolves EC Policies

Swarm begins EC policy evaluation by eliminating contexts (domain and bucket) not applicable, for one of two reasons:

  • Type of object 

  • "anchored" override 

Swarm (1) selects the anchored policy if it exists, or else (2) checks the relevant contexts from the bottom up and selects the first policy it finds: 

Example EC Policy Resolution

For example, consider a set of conflicting context-level policies such as this:

Cluster

Configuration setting

policy.ecEncoding

7:3



Domain

Persisted header

Policy-ECEncoding

Policy-ECEncoding-Unnamed

5:2 anchored

5:2





Bucket

Persisted header

Policy-ECEncoding

disabled

The EC policy evaluation resolves differently depending on the type of object being written:

Object Type

Evaluates to

Explanation

Object Type

Evaluates to

Explanation

named

5:2

The bucket setting is ignored because the domain setting is anchored.

tenanted unnamed

5:2

The bucket setting is ignored because unnamed objects cannot reside in a bucket.

The Policy-ECEncoding-Unnamed needs to be defaulted to the cluster value if it is unspecified.

untenanted unnamed

7:3

The domain setting is ignored because untenanted objects cannot reside in a domain.



Tip

See the diagram in Troubleshooting Erasure Coding to see how Swarm resolves the protection policy (whether to use erasure coding or replication) on a request.

How to View and Set EC Encoding Policy

EC Encoding is one of several content protection features in Swarm, all are controlled by way of policies. Swarm evaluates policies for each object based on cluster and context values:

  • Policy-related settings for the cluster (required) 

  • Policy-related headers on domain and bucket objects (optional)

For setting policies at the cluster level, see Configuring Cluster Policies.

Creating a policy involves changing one or both EC requirements for the given scope:

ecEncoding - Whether to allow/prevent/change the EC encoding 

ecMinStreamSize* - Whether to change the object size triggering erasure-coding. 

Important

For efficiency, ecMinStreamSize* is given in units of nMB and nGB, not bytes, as are the old settings. Convert (not copy) the old ec.minStreamSize value to the new setting specifying units. Note: 1 MB = 1,000,000 bytes.

Set encoding policies with the appropriate naming and method, starting with the cluster, once decided on the encoding policy for each level:

Scope

Type

Persisted Name, SNMP MIB

Configuration Method

Scope

Type

Persisted Name, SNMP MIB

Configuration Method

cluster

Configuration
setting

policy.ecEncoding, policyECEncoding

policy.ecMinStreamSize, policyECMinStreamSize

Set the cluster parameters specific to EC encoding policy and verify the other EC-related settings.

Use the snmpset command on the cluster's settings object to change and persist the cluster-wide policies. See Using SNMP with Swarm.

See Configuring Cluster Policies.

domain

Persisted
header

Policy-ECEncoding, policyECEncoding

Policy-ECMinStreamSize, policyECMinStreamSize

Policy-ECEncoding-Unnamed, policyECEncodingUnnamed

Policy-ECMinStreamSize-Unnamed, policyECMinStreamSizeUnnamed

Use a write method (POST for new, COPY for update) on the domain object to set policy values.

Use a read method (GET, HEAD) on the domain object to check policy values.

Separate encoding can be specified for unnamed objects, as if they are in a separate bucket, because they are tenanted directly in domains:

  • Set Policy-ECEncoding-Unnamed to allow/prevent/change erasure-coding of unnamed objects in this domain.

  • Set Policy-ECMinStreamSize-Unnamed to change the size to trigger erasure-coding of unnamed objects in this domain.

bucket

Persisted
header

Policy-ECEncoding, policyECEncoding

Policy-ECMinStreamSize, policyECMinStreamSize

Use a write method (POST for new, COPY for update) on the bucket object to set policy values.

Use a read method (GET, HEAD) on the bucket object to check policy values.

This new domain has a separate required policy for named objects (which bucket owners are not able to override), but unnamed objects follow the current cluster-level policy:

Writing a domain policy

This new bucket disables erasure-coding, but this policy is canceled by any policies "anchored" above it at the domain or cluster level:

Writing a bucket policy



© DataCore Software Corporation. · https://www.datacore.com · All rights reserved.