Skip to content

VSCP-5969: Support for large-capacity volumes #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jiljithcp wants to merge 1 commit into
base: main
Choose a base branch
from
Open

VSCP-5969: Support for large-capacity volumes #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ You are an expert helper for managing Google Cloud NetApp Volumes (GCNV) using t
- Default transport is stdio; start HTTP with `npm run start:http` or `node build/index.js --transport http --port <port>`.
- If you change the port, adjust the URL accordingly.
- Prefer stdio for CLI/editor use; use HTTP for browser/SSE integrations.
- **GCNV REST API (what MCP tools call):** This is separate from the MCP transport URL above. The server uses `@google-cloud/netapp` with `apiEndpoint` taken from the **`GCNV_API_ENDPOINT`** environment variable when it is set; if unset, the client uses Google’s default production NetApp Volumes API host. Request URLs are therefore `https://<apiEndpoint>/...` (exact paths are chosen by the client library). When a user asks what URL or host the **API** uses, answer with **stdio vs HTTP MCP** only if they asked about MCP wiring; for **Google API** calls, state the effective **`GCNV_API_ENDPOINT`** value (or that it is unset and the library default applies)—do **not** reply with `localhost` unless they are explicitly asking about HTTP MCP mode.
- **Authentication:** Assume Google Application Default Credentials are configured.
- On authentication errors, remind the user to set `GOOGLE_APPLICATION_CREDENTIALS` or run:
```
Expand Down Expand Up @@ -50,7 +51,7 @@ Use this link to explain billing and estimate pricing (pair with the Google Clou
- For **FLEX storage pool creation** only: if `location` is a **zone** (e.g., `us-central1-a`), that satisfies "zone in location" and you can omit `zone`/`replicaZone`. If `location` is a **region** (e.g., `us-central1`), the user must provide both `zone` and `replicaZone`.
- **For list tools (`gcnv_*_list`), `location` is optional.** If the user does not specify a location (e.g. "list my storage pools", "list all volumes"), omit the `location` parameter or pass `-`; the API will return resources from all locations. Do not ask for a location when the user only wants a full list.

### Request construction
### Request constructionf

- When building nested objects—export policies, protocol settings, replication configs—include **only fields the user specifies**.
- Do not auto-populate defaults unless the official API mandates them and the user has not provided alternatives.
Expand Down Expand Up @@ -120,17 +121,23 @@ Notes:
- Users often type `flex` in lowercase; the server accepts `serviceLevel` case-insensitively for pool creation (for example `flex` or `FLEX`).
- Minimum storage pool capacity (this project’s guidance):
- `FLEX`:
- `FILE` / `UNIFIED`: **1024 GiB**
- `UNIFIED_LARGE_CAPACITY`: **6 TiB (6144 GiB)**
- `FILE` / `UNIFIED` (default scale): **1024 GiB**
- `UNIFIED` (large capacity / scale-out): **6 TiB (6144 GiB)**
- `STANDARD`, `PREMIUM`, `EXTREME`: **2048 GiB**
- Flex custom performance: users can optionally provide `totalThroughputMibps` (MiBps) when creating a **FLEX** pool. This is only supported in select regions; if the API rejects it, suggest using default performance or a supported region/zone.
- Manual QoS: `qosType` can be `AUTO` or `MANUAL` for storage pools. Manual QoS is supported for Standard/Premium/Extreme and **isn't available for Flex**. See the Google Cloud docs: `https://docs.cloud.google.com/netapp/volumes/docs/performance/optimize-performance#set_up_manual_qos_limits`.
- FLEX location rules:
- If `location` is a **zone** (e.g. `us-central1-a`), that satisfies “zone in location” for FLEX pool creation and the request body should omit `zone`/`replicaZone`.
- If `location` is a **region** (e.g. `us-central1`), FLEX pool creation requires both `zone` and `replicaZone`.
- StoragePoolType:
- Users can optionally provide `storagePoolType` (`FILE`, `UNIFIED`, `UNIFIED_LARGE_CAPACITY`).
- `UNIFIED` and `UNIFIED_LARGE_CAPACITY` are only supported for **FLEX** service level.
- Users can optionally provide `storagePoolType` (`FILE`, `UNIFIED`).
- `UNIFIED` is only supported for **FLEX** service level.
- ScaleType:
- `scaleType` is **only applicable to FLEX `UNIFIED` pools**. Do not send it for `FILE` pools or non-FLEX service levels (Standard/Premium/Extreme).
- Users can optionally provide `scaleType` (`SCALE_TYPE_DEFAULT`, `SCALE_TYPE_SCALEOUT`).
- `SCALE_TYPE_DEFAULT`: standard capacity and performance, suitable for general purpose workloads. Use for standard `UNIFIED` pools.
- `SCALE_TYPE_SCALEOUT`: higher capacity and performance, suitable for more demanding workloads. Use for large capacity `UNIFIED` pools.
- **`scaleType` must always be set explicitly by the user.** Do not infer it from capacity — a `UNIFIED` pool of any size can be either `SCALE_TYPE_DEFAULT` or `SCALE_TYPE_SCALEOUT`. Always ask the user which scale type they want when creating a FLEX `UNIFIED` pool if they have not specified it.
- In simple terms:
- **FLEX** is the newer service level focused on flexibility (smaller minimum sizes and, in some regions, more independent performance scaling). It is also available in many more regions.
- **STANDARD / PREMIUM / EXTREME** are the classic tiers; Premium and Extreme are higher-performance tiers than Standard.
Expand Down Expand Up @@ -159,7 +166,7 @@ Notes:
- Pool: set `allowAutoTiering: true` when creating the storage pool.
- Volume: set `tieringPolicy` on the volume (for example `tierAction: ENABLED`, optional `coolingThresholdDays`, optional `hotTierBypassModeEnabled`).
- Hybrid replication: set `hybridReplicationParameters` on the volume (for example `replicationSchedule: HOURLY` and `hybridReplicationType: CONTINUOUS_REPLICATION`) along with peer details (cluster/SVM/IPs).
- Large capacity volumes: set `largeCapacity: true` (Premium/Extreme only; minimum 15 TiB) and optionally `multipleEndpoints: true` for multiple storage endpoints. See the volume limits and overview docs.
- Large capacity volumes: set `largeCapacity: true`. Required when the storage pool is a Unified scale-out / large-capacity pool — volumes in such pools must themselves be large-capacity. The MCP server sends `largeCapacityConfig: {}` on the wire (Volume field 46); the legacy `largeCapacity` boolean is for legacy FILE pools only. FLEX scale-out / PREMIUM / EXTREME; minimum **4916 GiB**. Optional `multipleEndpoints: true`.
- SMB attributes (only when `protocols` includes `SMB`):
- Boolean shortcuts on `gcnv_volume_create`:
- `smbEncryptData: true` → SMB encryption (`ENCRYPT_DATA`)
Expand Down
8 changes: 6 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,10 +113,12 @@ HTTP endpoint: `http://localhost:<port>/message`

**Service level guidance:**

- **FLEX** -- Smaller minimums, broader region availability, independent performance scaling. Minimum: 1024 GiB (FILE/UNIFIED) or 6144 GiB (UNIFIED_LARGE_CAPACITY).
- **FLEX** -- Smaller minimums, broader region availability, independent performance scaling. Minimum: 1024 GiB (FILE/UNIFIED) or 6144 GiB (UNIFIED large capacity).
- **STANDARD / PREMIUM / EXTREME** -- Classic tiers with fixed performance-to-capacity ratio. Minimum: 2048 GiB.
- `serviceLevel` is accepted case-insensitively (e.g. `flex` or `FLEX`).
- FLEX pools in a region-level location require both `zone` and `replicaZone`; zone-level locations satisfy this automatically.
- `storagePoolType` accepts `FILE` or `UNIFIED`; `UNIFIED` is only available for FLEX.
- `scaleType` accepts `SCALE_TYPE_DEFAULT` (standard capacity, general purpose) or `SCALE_TYPE_SCALEOUT` (higher capacity and performance, used for large capacity UNIFIED pools).

### Volume Tools

Expand All @@ -130,7 +132,9 @@ HTTP endpoint: `http://localhost:<port>/message`

**iSCSI notes:** Protocols must be `["ISCSI"]` only (no mixing). Requires `hostGroup` or `hostGroups`. Optional `blockDevice` object with `identifier`, `osType` (`LINUX` / `WINDOWS` / `ESXI`), and `sizeGib`.

**Large capacity volumes:** Set `largeCapacity: true` (Premium/Extreme only, minimum 15 TiB). Optional `multipleEndpoints: true`.
**Large capacity volumes:** Set `largeCapacity: true` to create a large-capacity volume. Required when the storage pool is a Unified scale-out / large-capacity pool (volumes in such pools must themselves be large-capacity). The MCP server sends `largeCapacityConfig: {}` (Volume field 46) — the legacy `largeCapacity` boolean is reserved for legacy FILE pools and is mutually exclusive. FLEX scale-out / PREMIUM / EXTREME; minimum 4916 GiB. Optional `multipleEndpoints: true`.

> Note: `LargeCapacityConfig` is not yet shipped in `@google-cloud/netapp@0.17.1`. This repo applies a small `patch-package` patch (`patches/@google-cloud+netapp+0.17.1.patch`) to add the message + Volume field 46 to the bundled proto so the gRPC client can serialize it. The patch is applied automatically via the `postinstall` script.

**SMB attributes:** When `protocols` includes `SMB`, `gcnv_volume_create` accepts optional SMB feature flags that map to the `smbSettings` field on the volume:

Expand Down
Loading
Loading