Use Case: Apply Snapshot Policy to Volume¶

Overview¶

This use case describes how to apply an existing Snapshot policy to a Volume using the NetApp API. Once applied, the volume will follow the snapshot schedule and retention rules defined in the policy.

API Endpoint¶

PATCH /api/storage/volumes/{volume_uuid}
Permissions: cluster-admin or volume-admin

Sequence Diagram¶

sequenceDiagram
    participant Client
    participant NetApp_API
    participant ONTAP_Cluster
    participant Volume

    Client->>NetApp_API: GET /api/storage/volumes?name=<volume_name>
    NetApp_API->>ONTAP_Cluster: Find Volume by Name
    ONTAP_Cluster-->>NetApp_API: Volume UUID
    NetApp_API-->>Client: Volume UUID

    Client->>NetApp_API: PATCH /api/storage/volumes/{volume_uuid}
    Note over Client,NetApp_API: Apply Snapshot Policy

    NetApp_API->>ONTAP_Cluster: Find Volume by UUID
    alt Volume Found
        ONTAP_Cluster->>ONTAP_Cluster: Find Snapshot Policy
        alt Policy Found
            ONTAP_Cluster->>Volume: Apply Policy
            Volume-->>ONTAP_Cluster: Policy Applied
            ONTAP_Cluster-->>NetApp_API: Success Confirmation
            NetApp_API-->>Client: 200 OK
        else Policy Not Found
            ONTAP_Cluster-->>NetApp_API: Policy Not Found Error
            NetApp_API-->>Client: 404 Not Found
        end
    else Volume Not Found
        ONTAP_Cluster-->>NetApp_API: Volume Not Found Error
        NetApp_API-->>Client: 404 Not Found
    else Authorization Error
        NetApp_API-->>Client: 403 Forbidden
    else System Error
        ONTAP_Cluster-->>NetApp_API: Internal Error
        NetApp_API-->>Client: 500 Internal Server Error
    end

Inputs¶

Authentication¶

Username: NetApp ONTAP API username with cluster-admin or volume-admin privileges
Password: Corresponding password for API authentication
Base URL: NetApp ONTAP cluster management IP or FQDN (e.g., https://cluster1.example.com)

Volume Identification¶

Volume Name: Name of the target volume (e.g., volume_prod_data)
Volume UUID: Unique identifier of the target volume (alternative to volume name)
SVM Name: Storage Virtual Machine name where the volume resides (if filtering by SVM)

Snapshot Policy Information¶

Policy Name: Name of the existing snapshot policy to apply (e.g., Daily_and_Weekly_Snapshots)
Policy UUID: Unique identifier of the snapshot policy (alternative to policy name)

Request Parameters (for GET /api/storage/volumes)¶

name: Filter volumes by name
svm.name: Filter volumes by SVM name
uuid: Filter by specific volume UUID
fields: Specify which fields to return (e.g., name,uuid,svm,snapshot_policy)
max_records: Maximum number of records to return (default: 10000)
order_by: Sort results by specified field

PATCH Request Body¶

{
  "snapshot_policy": {
    "name": "Daily_and_Weekly_Snapshots"
  }
}

Alternative Request Body (using UUID)¶

{
  "snapshot_policy": {
    "uuid": "12345678-1234-1234-1234-123456789012"
  }
}

Input Validation Requirements¶

Volume must exist and be accessible
Snapshot policy must exist in the same cluster
User must have appropriate permissions (cluster-admin or volume-admin)
Volume must be online and available
Sufficient space should be available for snapshot creation

Prerequisites¶

The snapshot policy must exist in the cluster
The target volume must exist and be accessible
Sufficient space must be available for snapshots

Request Body¶

The request body should specify the snapshot policy to apply to the volume:

{
  "snapshot_policy": {
    "name": "Daily_and_Weekly_Snapshots"
  }
}

Example with `curl`¶

Here's how you can apply a snapshot policy to a volume using curl:

# First, get the volume UUID
curl -X GET "https://<netapp-ip>/api/storage/volumes?name=<volume_name>" \
     -H "Authorization: Basic <base64_auth_token>" \
     -H "Content-Type: application/json"

# Then apply the policy using the UUID
curl -X PATCH "https://<netapp-ip>/api/storage/volumes/<volume_uuid>" \
     -H "Authorization: Basic <base64_auth_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "snapshot_policy": {
         "name": "Daily_and_Weekly_Snapshots"
       }
     }'

Complete Example Script¶

Here's a complete bash script that finds a volume by name and applies a snapshot policy:

#!/bin/bash

NETAPP_IP="your-netapp-cluster-ip"
AUTH_TOKEN="your-base64-auth-token"
VOLUME_NAME="volume_prod_data"
POLICY_NAME="Daily_and_Weekly_Snapshots"

# Get volume UUID
VOLUME_UUID=$(curl -s -X GET "https://${NETAPP_IP}/api/storage/volumes?name=${VOLUME_NAME}" \
  -H "Authorization: Basic ${AUTH_TOKEN}" \
  -H "Content-Type: application/json" | \
  jq -r '.records[0].uuid')

if [ "$VOLUME_UUID" = "null" ]; then
  echo "Volume $VOLUME_NAME not found"
  exit 1
fi

echo "Found volume UUID: $VOLUME_UUID"

# Apply snapshot policy
curl -X PATCH "https://${NETAPP_IP}/api/storage/volumes/${VOLUME_UUID}" \
     -H "Authorization: Basic ${AUTH_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "{
       \"snapshot_policy\": {
         \"name\": \"${POLICY_NAME}\"
       }
     }"

echo "Snapshot policy '${POLICY_NAME}' applied to volume '${VOLUME_NAME}'"

Verification¶

To verify that the snapshot policy has been applied successfully:

curl -X GET "https://<netapp-ip>/api/storage/volumes/<volume_uuid>?fields=snapshot_policy" \
     -H "Authorization: Basic <base64_auth_token>" \
     -H "Content-Type: application/json"

Best Practices¶

Verify that the snapshot policy exists before applying it to a volume
Monitor the volume's available space after applying snapshot policies
Consider the performance impact of frequent snapshots on high-throughput volumes
Test snapshot policies on non-production volumes first
Document which volumes use which snapshot policies for easier management

Error Handling¶

Common errors when applying snapshot policies:

404 Not Found: The volume UUID or snapshot policy name doesn't exist
403 Forbidden: Insufficient permissions to modify the volume
400 Bad Request: Invalid policy name or malformed request body

Always check the API response for error details and handle them appropriately in your automation scripts.