Self-service maintenance lets you apply maintenance upgrades to
your Managed Lustre instances on demand.

When Managed Lustre releases a new software version, it becomes
available immediately for self-service maintenance. This is typically several
weeks before automated maintenance reaches your instance.

You can perform self-service maintenance at any time once a version is
available. If your instance has a maintenance policy, you can perform
self-service maintenance up until 1 hour before a scheduled maintenance window.

For an overview of maintenance impact and policies, see
[Maintenance overview](https://docs.cloud.google.com/managed-lustre/docs/maintenance.md.txt).

## Check available maintenance versions

Managed Lustre instances track maintenance releases using the
following version fields:

- `effectiveVersion`: Output only. The software release version running on your instance. For example, `Lustre_20260516.00_p00`.
- `availableVersion`: Output only. A qualified, newer software release version that your instance is eligible to upgrade to. If this field is empty, your instance is already running the latest available release.
- `targetVersion`: Input only. The parameter specified in an update request to initiate an upgrade to a candidate version or to `latest`.

To verify your instance's current version and check whether an upgrade is
available:

### Google Cloud console

1. In the Google Cloud console, go to the **Managed Lustre** page:

   [Go to Managed Lustre](https://console.cloud.google.com/managed-lustre/)
2. In the instances list, locate your instance. If a newer maintenance version
   is available, an **Update available** badge appears next to the `ACTIVE`
   status.

3. Click the instance name to open the **Instance details** page to view the
   available version string.

### gcloud CLI

Run the [`gcloud lustre instances describe`](https://docs.cloud.google.com/sdk/gcloud/reference/lustre/instances/describe) command with a format
filter:

```bash
gcloud lustre instances describe INSTANCE_ID \
  --location=LOCATION \
  --format="yaml(effectiveVersion, availableVersion, state)"
```

Replace the following:

- <var translate="no">INSTANCE_ID</var>: The ID of your Managed Lustre instance.
- <var translate="no">LOCATION</var>: The zone where your instance is located.

If a newer version is available, the output resembles the following:

```yaml
availableVersion: Lustre_20260716.01_p00
effectiveVersion: Lustre_20260516.00_p00
state: ACTIVE
```

If `availableVersion` is empty, your instance is already running the latest
available release.

### REST

To check the version details for an instance, send a `GET` request to the
instance endpoint:

```json
GET https://lustre.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID
Authorization: Bearer ACCESS_TOKEN
```

Where:

- <var translate="no">PROJECT_ID</var> is your Google Cloud project ID.
- <var translate="no">LOCATION</var> is the zone in which the instance resides.
- <var translate="no">INSTANCE_ID</var> is the ID of the Managed Lustre instance.

If a newer version is available, the response contains `effectiveVersion`
and `availableVersion`:

```json
{
  "name": "projects/my-project/locations/us-central1-a/instances/my-instance",
  "state": "ACTIVE",
  "effectiveVersion": "Lustre_20260516.00_p00",
  "availableVersion": "Lustre_20260716.01_p00"
}
```

If `availableVersion` is omitted or empty, your instance is already running
the latest available release.

See the [`instances.get`](https://docs.cloud.google.com/managed-lustre/docs/reference/rest/v1/projects.locations.instances/get.md.txt) API reference for more details.

## Perform a self-service upgrade

To upgrade your instance to an available software version:

### gcloud CLI

Run the [`gcloud lustre instances update`](https://docs.cloud.google.com/sdk/gcloud/reference/lustre/instances/update.md.txt) command with the
`--target-version` flag:

```bash
gcloud lustre instances update INSTANCE_ID \
  --location=LOCATION \
  --target-version=latest
```

Replace the following:

- <var translate="no">INSTANCE_ID</var>: The ID of your Managed Lustre instance.
- <var translate="no">LOCATION</var>: The zone where your instance is located.

To upgrade to a specific qualified release version instead of `latest`, pass
the version string:

```bash
gcloud lustre instances update INSTANCE_ID \
  --location=LOCATION \
  --target-version=TARGET_VERSION
```

Replace <var translate="no">TARGET_VERSION</var> with the version string from
`availableVersion`. For example, `Lustre_20260716.01_p00`.

### REST

To upgrade an instance using the REST API, send a `PATCH` request to the
instance endpoint, specifying `targetVersion` in the `updateMask` query
parameter:

```json
PATCH https://lustre.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID?updateMask=targetVersion
Authorization: Bearer ACCESS_TOKEN

{
  "targetVersion": "latest"
}
```

Where:

- <var translate="no">PROJECT_ID</var> is your Google Cloud project ID.
- <var translate="no">LOCATION</var> is the zone in which the instance resides.
- <var translate="no">INSTANCE_ID</var> is the ID of the Managed Lustre instance.

To upgrade to a specific qualified release version instead of `latest`,
specify the version string in the request body, such as
`"targetVersion": "Lustre_20260716.01_p00"`.

See the [`instances.patch`](https://docs.cloud.google.com/managed-lustre/docs/reference/rest/v1/projects.locations.instances/patch.md.txt) API reference for more details.

## Track maintenance progress

The upgrade executes as an asynchronous long-running operation.
Self-service maintenance doesn't trigger automated notification emails.

To track progress in real time:

### gcloud CLI

Poll the operation status using the
[`gcloud lustre operations describe`](https://docs.cloud.google.com/sdk/gcloud/reference/lustre/operations/describe) command:

```bash
gcloud lustre operations describe OPERATION_ID \
  --location=LOCATION
```

Replace the following:

- <var translate="no">OPERATION_ID</var>: The operation ID returned by the update command.
- <var translate="no">LOCATION</var>: The zone where your instance is located.

The instance state displays `UPGRADING` while the upgrade is in progress and
returns to `ACTIVE` once complete.

### REST

Send a `GET` request to the [`operations.get`](https://docs.cloud.google.com/managed-lustre/docs/reference/rest/v1/projects.locations.operations/get.md.txt) endpoint:

```json
GET https://lustre.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Authorization: Bearer ACCESS_TOKEN
```

Where:

- <var translate="no">PROJECT_ID</var> is your Google Cloud project ID.
- <var translate="no">LOCATION</var> is the zone in which the instance resides.
- <var translate="no">OPERATION_ID</var> is the operation ID returned by the update request.

See the [`operations.get`](https://docs.cloud.google.com/managed-lustre/docs/reference/rest/v1/projects.locations.operations/get.md.txt) API reference for more details.

When the upgrade succeeds:

1. The instance returns to `ACTIVE` state.
2. `effectiveVersion` reflects the newly applied version string.
3. `availableVersion` is cleared and omitted from API responses.

## Interaction with scheduled maintenance

If your instance has upcoming scheduled maintenance, successfully
completing a self-service upgrade automatically cancels that upcoming scheduled
maintenance. If you're
[subscribed to maintenance notifications](https://docs.cloud.google.com/managed-lustre/docs/maintenance-notifications.md.txt#notifications),
you receive an automated **Maintenance canceled** email notification.

If a self-service upgrade fails, the pending scheduled maintenance window is not
canceled. The instance returns to `ACTIVE` state on its current version, and
the scheduled maintenance window is retained.

You cannot trigger a self-service upgrade within 1 hour of an upcoming scheduled
maintenance window. Attempting to initiate an upgrade during this period returns
a `409 CONFLICT` error to avoid overlapping with the upcoming scheduled
maintenance.

## Error messages

Possible self-service maintenance errors include:

- **`Instance is already running version "<CURRENT>"`**: Occurs if you attempt to upgrade to the software version already running on the instance.
- **`Downgrading to a lower version is not supported.`**: Occurs if you attempt to downgrade to an earlier software version.
- **`Version "<TARGET>" is not a valid update version.`** : Occurs if the specified version does not match the instance's `availableVersion` string or `latest`.
- **`Instance must be in ACTIVE state to update version`** : Occurs if an upgrade is initiated while the instance is not in the `ACTIVE` state.
- **`Cannot trigger self-service update within 1 hour of a scheduled
  maintenance window`**: Occurs if a self-service upgrade is initiated less than 1 hour before an upcoming scheduled maintenance window.