Managing Update Policies

This workflow covers configuring update policies that control how clients receive updates. Policies can be set at global, tenant, product, or tenant-product levels.

Prerequisites

API credentials with policy management permissions
Understanding of your organization’s update requirements
Knowledge of version pinning and blocklist needs

Understanding Update Policies

Update policies control:

Update mode — How clients handle updates (AUTO_INSTALL, NOTIFY_ONLY, MANAGED_BY_IT)
Version pinning — Lock to specific version ranges
Blocklists — Prevent specific versions from being distributed

Policies are evaluated in precedence order: tenant-product → product → tenant → global.

Step 1: Check Current Policy

Query current policy for a tenant-product combination:

curl "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "policy_id": "policy_abc123",
  "tenant_id": "tenant_abc123",
  "product_id": "prod_xyz789",
  "channel": "stable",
  "mode": "NOTIFY_ONLY",
  "pinned_range": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Step 2: Create or Update Policy

Create or update a tenant-product policy:

curl -X PUT "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "AUTO_INSTALL",
    "pinned_range": null
  }'

Update modes:

AUTO_INSTALL — Clients may install updates automatically
NOTIFY_ONLY — Clients notify users but don’t install
MANAGED_BY_IT — Clients defer to IT-managed deployment

Response:

{
  "policy_id": "policy_abc123",
  "tenant_id": "tenant_abc123",
  "product_id": "prod_xyz789",
  "channel": "stable",
  "mode": "AUTO_INSTALL",
  "pinned_range": null,
  "updated_at": "2024-01-15T10:35:00Z"
}

Step 3: Configure Version Pinning

Pin to a specific version range. Tenant-product policies are customer-specific and have the highest precedence, allowing you to pin versions for individual customers.

curl -X PUT "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "NOTIFY_ONLY",
    "pinned_range": ">=1.2.0,<2.0.0"
  }'

Pinning examples:

"1.2.3" — Exact version pin
">=1.2.0,<2.0.0" — Version range pin (allow 1.x, block 2.x)
">=1.0.0,<2.0.0" — Major version pin (block major upgrades)

Customer-specific pinning: Tenant-product policies apply to a specific customer (tenant) and product combination. This allows different customers to have different version pinning requirements.

Step 4: Add Blocklist Entry

Block a specific version:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/blocklist" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "blocked_version": "1.2.3",
    "reason": "CVE-2024-12345: Critical security vulnerability"
  }'

Response:

{
  "blocklist_id": "block_abc123",
  "tenant_id": "tenant_abc123",
  "product_id": "prod_xyz789",
  "blocked_version": "1.2.3",
  "reason": "CVE-2024-12345: Critical security vulnerability",
  "blocked_at": "2024-01-15T10:40:00Z",
  "blocked_by": "admin@example.com"
}

Step 5: Remove Blocklist Entry

Remove a version from the blocklist:

curl -X DELETE "${BP_BASE_URL}/v1/tenants/tenant_abc123/blocklist/prod_xyz789/1.2.3" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Step 6: Test Policy Evaluation

Test how a policy evaluates for specific versions:

curl -X POST "${BP_BASE_URL}/v1/policies/test" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_abc123",
    "product_id": "prod_xyz789",
    "current_version": "1.1.0",
    "available_version": "1.3.0"
  }'

Response:

{
  "action": "INSTALL",
  "rationale": "Policy: AUTO_INSTALL, version within pinned range",
  "policy_applied": {
    "mode": "AUTO_INSTALL",
    "pinned_range": ">=1.2.0,<2.0.0"
  }
}

Policy Precedence

Policies are evaluated in this order (highest to lowest):

Tenant-product policy — Specific to tenant-product combination
Product policy — Applies to all tenants for a product
Tenant policy — Applies to all products for a tenant
Global policy — Default policy for all tenants/products

Higher precedence policies override lower precedence ones.

Global Policy

Set a global policy (applies to all tenants/products):

curl -X PUT "${BP_BASE_URL}/v1/policies/global/prod_xyz789" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "NOTIFY_ONLY",
    "pinned_range": null
  }'

Product Policy

Set a product policy (applies to all tenants):

curl -X PUT "${BP_BASE_URL}/v1/products/prod_xyz789/policies" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "AUTO_INSTALL",
    "pinned_range": null
  }'

Tenant Policy

Set a tenant policy (applies to all products):

curl -X PUT "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "MANAGED_BY_IT",
    "pinned_range": null
  }'

Policy History

View policy change history:

curl "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789/history" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "policy_id": "policy_abc123",
  "history": [
    {
      "version": "policy_version_1",
      "mode": "NOTIFY_ONLY",
      "pinned_range": null,
      "updated_at": "2024-01-15T10:30:00Z",
      "updated_by": "admin@example.com"
    },
    {
      "version": "policy_version_2",
      "mode": "AUTO_INSTALL",
      "pinned_range": ">=1.2.0,<2.0.0",
      "updated_at": "2024-01-15T10:35:00Z",
      "updated_by": "admin@example.com"
    }
  ]
}

Rollback Policy

Rollback to a previous policy version:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/policies/prod_xyz789/rollback" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_version": "policy_version_1"
  }'

Best Practices

Test before deploying: Test policies with sample versions before deploying to production.

Document rationale: Document why policies are configured as they are.

Use version pinning: Pin to version ranges for critical environments to prevent unexpected upgrades.

Maintain blocklists: Keep blocklists up to date with known problematic versions.

Monitor policy effectiveness: Track how policies affect update behavior.

Use policy history: Keep audit trail of policy changes for compliance.

Start with global policies: Set global defaults, then override with specific policies as needed.

Next Steps

Manage release versions — see Managing Release Versions
Handle rollbacks — see Handling Rollbacks
Track license usage — see Tracking License Usage