Inspect and release volumes - Namespace Documentation

client.storage covers the two volume types Namespace attaches to instances. Cache volumes are identified by a tag and reused across runs, with one generation per use. Persistent volumes are block volumes with their own identity and snapshots. The examples on this page use a Compute client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

`storage.listCacheVolumes()`

Return every cache volume in the workspace.

Example

const { cacheVolume } = await client.storage.listCacheVolumes({});

for (const volume of cacheVolume) {
  console.log(volume.id, volume.tag, volume.metadata?.sizeMb);
}

API reference

listCacheVolumes(
  request: MessageInitShape<typeof ListCacheVolumesRequestSchema>,
  options?: CallOptions,
): Promise<ListCacheVolumesResponse>

Arguments and options

The request has no fields. Pass an empty object.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListCacheVolumesResponse with cacheVolume, a list of CacheVolume. Each entry carries id, tag, metadata with the lifecycle timestamps, size, and state, and attachment with the instance the volume was attached to and its utilization.

`storage.getCacheVolume()`

Return a single cache volume generation by ID.

Example

const { cacheVolume } = await client.storage.getCacheVolume({ id: volumeId });

console.log(cacheVolume?.metadata?.state);

API reference

getCacheVolume(
  request: MessageInitShape<typeof GetCacheVolumeRequestSchema>,
  options?: CallOptions,
): Promise<GetCacheVolumeResponse>

Arguments and options

string

required

The unique identifier of the cache volume generation. A single tag can have multiple generations over time.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetCacheVolumeResponse with the matching cacheVolume.

`storage.listVolumeTagSummaries()`

Summarize every cache volume tag in the workspace. Use this to see cache usage per tag rather than per generation.

Example

const { summaries } = await client.storage.listVolumeTagSummaries({});

for (const summary of summaries) {
  console.log(summary.tag, summary.sizeMb, summary.generations.length);
}

API reference

listVolumeTagSummaries(
  request: MessageInitShape<typeof ListVolumeTagSummariesRequestSchema>,
  options?: CallOptions,
): Promise<ListVolumeTagSummariesResponse>

Arguments and options

The request has no fields. Pass an empty object.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListVolumeTagSummariesResponse with summaries, a list of TagSummary. Each summary carries the tag, its requested sizeMb, and the generations that belong to it.

`storage.getVolumeTagSummary()`

Summarize a single cache volume tag.

Example

const { summary } = await client.storage.getVolumeTagSummary({ tag: "node-modules" });

console.log(summary?.sizeMb);

API reference

getVolumeTagSummary(
  request: MessageInitShape<typeof GetVolumeTagSummaryRequestSchema>,
  options?: CallOptions,
): Promise<GetVolumeTagSummaryResponse>

Arguments and options

string

required

The name of the cache volume tag.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetVolumeTagSummaryResponse with the matching TagSummary.

`storage.destroyCacheVolume()`

Release all cache volumes that belong to a tag.

Example

await client.storage.destroyCacheVolume({ tag: "node-modules" });

API reference

destroyCacheVolume(
  request: MessageInitShape<typeof DestroyCacheVolumeRequestSchema>,
  options?: CallOptions,
): Promise<Empty>

Arguments and options

string

required

The cache volume tag to release.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an empty response. Omitting the tag fails with InvalidArgument, and an unknown tag fails with NotFound.

Releasing a cache volume cannot be undone. The next run that uses the tag starts from an empty cache.

`storage.listPersistentVolumes()`

Return one page of persistent volumes, optionally filtered by tag and site.

Example

const page = await client.storage.listPersistentVolumes({
  tag: "workspace-data",
  maxEntries: 50n,
});

for (const volume of page.volumes) {
  console.log(volume.id, volume.site, volume.attachedTo);
}

API reference

listPersistentVolumes(
  request: MessageInitShape<typeof ListPersistentVolumesRequestSchema>,
  options?: CallOptions,
): Promise<ListPersistentVolumesResponse>

Arguments and options

string

Only return volumes with this tag. When omitted, all persistent volumes are returned.

StringMatcher

Only query the matching sites. When omitted, all sites are queried.

bigint

The maximum number of entries to return. The service may return fewer.

Uint8Array

The paginationCursor from a previous response, to continue reading results.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListPersistentVolumesResponse with volumes and a paginationCursor. A set cursor means more results are available. Each PersistentVolume carries id, tag, sizeMb, site, createdAt, attachedTo, and the release and destruction timestamps.

`storage.describePersistentVolume()`

Return details of a single persistent volume.

Example

const { volume } = await client.storage.describePersistentVolume({
  id: volumeId,
  tag: "workspace-data",
});

console.log(volume?.sizeMb, volume?.attachedTo);

API reference

describePersistentVolume(
  request: MessageInitShape<typeof DescribePersistentVolumeRequestSchema>,
  options?: CallOptions,
): Promise<DescribePersistentVolumeResponse>

Arguments and options

string

required

The unique identifier of the persistent volume.

string

required

The tag of the persistent volume.

string

The site the volume is located in. When provided, only that site is queried.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a DescribePersistentVolumeResponse with the matching volume. If the volume does not exist, the call fails with NotFound.

`storage.destroyPersistentVolumes()`

Destroy every persistent volume that matches the given criteria.

Example

import { StringMatcher_Operator } from "@namespacelabs/sdk/proto/namespace/stdlib/matchers_pb";

const { destroyedVolumes } = await client.storage.destroyPersistentVolumes({
  tag: {
    values: ["workspace-data"],
    op: StringMatcher_Operator.IS_ANY_OF,
  },
});

console.log(`destroyed ${destroyedVolumes.length} volumes`);

API reference

destroyPersistentVolumes(
  request: MessageInitShape<typeof DestroyPersistentVolumesRequestSchema>,
  options?: CallOptions,
): Promise<DestroyPersistentVolumesResponse>

Arguments and options

At least one of id or tag must be set. For safety the service rejects the IS_NOT operator.

StringMatcher

Matches volumes by ID.

StringMatcher

Matches volumes by tag.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a DestroyPersistentVolumesResponse with destroyedVolumes, the metadata of the volumes that were destroyed. Omitting both matchers or using IS_NOT fails with InvalidArgument. When no volume matches, the call fails with NotFound.

`storage.listPersistentVolumeSnapshots()`

Return every snapshot of a persistent volume.

Example

const { snapshots } = await client.storage.listPersistentVolumeSnapshots({
  id: volumeId,
  tag: "workspace-data",
});

for (const snapshot of snapshots) {
  console.log(snapshot.id, snapshot.usedBytes, snapshot.abandonedAt);
}

API reference

listPersistentVolumeSnapshots(
  request: MessageInitShape<typeof ListPersistentVolumeSnapshotsRequestSchema>,
  options?: CallOptions,
): Promise<ListPersistentVolumeSnapshotsResponse>

Arguments and options

string

required

The unique identifier of the persistent volume.

string

required

The tag of the persistent volume.

string

The site the volume is located in. When provided, only that site is queried.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListPersistentVolumeSnapshotsResponse with snapshots. Each PersistentVolumeSnapshot carries id, createdAt, usedBytes, netNewUsedBytes, the parent in snapshotFrom, and the attachment and release state.

`storage.destroyPersistentVolumeSnapshot()`

Mark a snapshot as abandoned. Abandoned snapshots are excluded when Namespace selects a base snapshot for new volumes, which is useful for skipping a corrupted snapshot without destroying the volume.

Example

const { snapshot } = await client.storage.destroyPersistentVolumeSnapshot({
  id: volumeId,
  tag: "workspace-data",
});

console.log(snapshot?.abandonedAt);

API reference

destroyPersistentVolumeSnapshot(
  request: MessageInitShape<typeof DestroyPersistentVolumeSnapshotRequestSchema>,
  options?: CallOptions,
): Promise<DestroyPersistentVolumeSnapshotResponse>

Arguments and options

string

required

The unique identifier of the snapshot, which is the volume ID.

string

required

The tag of the persistent volume.

string

The site the volume is located in. When provided, only that site is queried.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a DestroyPersistentVolumeSnapshotResponse with the abandoned snapshot. If the snapshot does not exist, the call fails with NotFound. If it is still attached to an instance, the call fails with FailedPrecondition.

Storage platform

Cache volumes, artifact storage, and the container registry.

Volume usage

Report on cache and persistent volume storage.

​storage.listCacheVolumes()

​Example

​API reference

​Arguments and options

​Return value

​storage.getCacheVolume()

​Example

​API reference

​Arguments and options

​Return value

​storage.listVolumeTagSummaries()

​Example

​API reference

​Arguments and options

​Return value

​storage.getVolumeTagSummary()

​Example

​API reference

​Arguments and options

​Return value

​storage.destroyCacheVolume()

​Example

​API reference

​Arguments and options

​Return value

​storage.listPersistentVolumes()

​Example

​API reference

​Arguments and options

​Return value

​storage.describePersistentVolume()

​Example

​API reference

​Arguments and options

​Return value

​storage.destroyPersistentVolumes()

​Example

​API reference

​Arguments and options

​Return value

​storage.listPersistentVolumeSnapshots()

​Example

​API reference

​Arguments and options

​Return value

​storage.destroyPersistentVolumeSnapshot()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Storage platform

Volume usage

`storage.listCacheVolumes()`

Example

API reference

Arguments and options

Return value

`storage.getCacheVolume()`

Example

API reference

Arguments and options

Return value

`storage.listVolumeTagSummaries()`

Example

API reference

Arguments and options

Return value

`storage.getVolumeTagSummary()`

Example

API reference

Arguments and options

Return value

`storage.destroyCacheVolume()`

Example

API reference

Arguments and options

Return value

`storage.listPersistentVolumes()`

Example

API reference

Arguments and options

Return value

`storage.describePersistentVolume()`

Example

API reference

Arguments and options

Return value

`storage.destroyPersistentVolumes()`

Example

API reference

Arguments and options

Return value

`storage.listPersistentVolumeSnapshots()`

Example

API reference

Arguments and options

Return value

`storage.destroyPersistentVolumeSnapshot()`

Example

API reference

Arguments and options

Return value

Related documentation