Cluster and Organization Operations
Use this reference to explain cluster settings, upgrades, Image Accelerator, storage monitoring, and organization access. Reading a setting does not change it. A recommendation to change it is not permission to execute that change.
The paths below are case-sensitive JSON paths under the MCP response data
unless another location is named. Optional or null fields mean unavailable or
not applicable, not false. Check the deployed tool schema and installed
component version before using a field: documentation coverage does not mean
every release exposes the same capabilities.
Cluster settings
Console: Cluster > Setting > General. MCP: get_cluster_settings with
organization_id and cluster_id. Values are returned under settings.
Defaults below are the server defaults for a newly initialized setting, not a
promise to overwrite existing clusters or a substitute for reading their state.
| Console setting | MCP path and type | Meaning, default, and constraints |
|---|---|---|
| Node Repair | settings.enableNodeRepair: boolean or null | Default true. Allows recovery of persistently unhealthy nodes; can evict workloads and remove faulty nodes. It is not a guarantee that every NotReady node will be immediately replaced. |
| Disk Monitor | settings.enableDiskMonitor: boolean or null | Default true. Collects node filesystem and PVC utilization. Disabling it stops that collection, not the underlying disks or PVCs. |
| NodePool Decommission | settings.enableNodePoolDecommission: boolean or null | Default false; supported for AWS, GCP, and Azure in the referenced implementation. Keeps existing nodes while a pool is decommissioned, then finalizes deletion after backing local capacity drains. Not an instruction to delete a pool. |
| Disruption Cooldown | settings.disruptionCooldown: duration string | Default 0s. Cluster default wait between completed disruption batches in each NodePool; a NodePool can override it. Non-negative combinations of integer h, m, and s, such as 30m. Budgets still constrain each batch. |
| AWS Spot Allocation Strategy | settings.awsSpotAllocationStrategy: string | AWS only; omitted for other providers. lowest-price (default) or price-capacity-optimized. Changes instance selection trade-offs, not workload eligibility for Spot. |
| Conservative Workload Defaults | settings.enableWorkloadMinNonSpot: boolean or null | Default false. Affects defaults for newly discovered NA workloads; it does not reset explicit workload settings. When disabled, those defaults are Rebalanceable, Spot Friendly, and zero minimum non-Spot replicas. |
| Enterprise Discount | settings.discount: number or null | Default 1. Cost multiplier in (0, 1]; an illustrative 0.8 means 80% of the undiscounted cost, not an 80% discount. Does not change the cloud invoice or purchase a commitment. |
| Maintenance Mode | settings.maintenanceEnabled: boolean or null | Reports whether customer-controlled support access is enabled. It does not mean optimization is paused. Follow the Console’s cluster-specific instructions and disable access when support finishes. |
| Saving Report default baseline | settings.savingReportBaselineStartAt, settings.savingReportBaselineEndAt: timestamps or null | A saved baseline range, separate from the report’s current comparison range. Both endpoints must be provided together and start must precede end. Read report baselineMode to see which baseline was actually used. |
| Pre/Post Run Command | settings.preRunCommand, settings.postRunCommand: strings or null | Shell hooks used by the relevant generated operation scripts. Reading them does not execute them. Do not put secrets in a support transcript or assume these hooks run for every controller action. |
Disruption Cooldown, AWS Spot Allocation Strategy, and NodePool Decommission are version-dependent. If a deployed API omits one of these fields, do not invent a value from this table. Confirm availability before proposing an update.
WA settings are returned by get_workload_autoscaler_configuration, not this
tool; see Workload Autoscaler.
NodePool-specific behavior is configured separately from cluster defaults;
see NodePool and
Node Optimization.
Upgrade and component state
MCP: get_cluster_upgrade_status. An upgrade operation concerns CloudPilot
components, not an upgrade of the Kubernetes control plane itself.
| MCP path | Type / values | How to use it |
|---|---|---|
installedVersion, latestVersion, availableTargetVersions | Strings; target list can be empty | Installed and offered CloudPilot release versions. An empty target list is not evidence that every possible target is safe. |
currentVersion, desiredVersion, desiredComponents | Strings and optional component-to-version map | Current operation’s source, target, and component versions. Desired is intent, not completion. |
operationId, startedAt, finishedAt, message | Optional ID/timestamps and message | Correlate an operation and inspect its result. Missing finish time does not establish success. |
status | pending, accepted, running, succeeded, failed, manual_required, timed_out | Only succeeded establishes operation success. manual_required means a prerequisite or manual checkpoint is necessary; do not repeatedly retry a write. |
phases[].name | workload-autoscaler, node-autoscaler, agent | Component phase, not a promise that every component is installed. |
phases[].status | pending, running, succeeded, failed, skipped | Read each phase and its message, fromVersion, toVersion, and timestamps. skipped is not the same as upgraded. |
phases[].workloadRefs[] | Object references | Target namespace, kind, name, container, and image. Use these to investigate the correct component, not an application workload with a similar name. |
phases[].crdBundles[], phases[].crdResults[] | Optional bundle/result lists | CRD prerequisites and outcomes. Result status is created, applied, unchanged, or failed. |
upgradePolicy.autoUpgradeable, imageOnly | Booleans | Whether the offered transition supports automatic upgrade and whether it is image-only. These describe that transition, not permanent cluster permissions. |
upgradePolicy.requiresRoleChange, requiresCRDChange | Booleans | Check cloud permissions and CRD prerequisites before executing the offered transition. |
upgradePolicy.allowedComponents | Component phase names | Components allowed by the offered upgrade policy. |
Follow the Upgrade Guide for execution. The read tool does not create an upgrade operation or run a script.
The Console’s Setting > Components view can additionally show Pod name/UID,
ready/total containers, status, restart count, creation time, and container
state/reason; its log viewer is a separate stream. These are not fields of
get_cluster_upgrade_status. Component inventory and logs do not currently have
a registered MCP read tool in the referenced catalog. TODO: add dedicated
reads only after their supported release and access/retention contract is
confirmed. Do not infer healthy component Pods from a successful past upgrade.
Image Accelerator
MCP: get_image_accelerator_status; node metrics:
list_image_accelerator_nodes. Configuration and observed traffic answer
different questions.
| Field / setting | Meaning |
|---|---|
Status supported: boolean or null | Whether this cluster can use the feature. Null is unknown, not supported. |
Status installed: boolean or null | Whether the cluster installation reports the component installed. This does not prove every node is enabled or that a particular pull used peers. |
Status nodeCount: integer | Count represented by the per-node metric inventory, not the total number of Kubernetes nodes. |
| NodePool Image Accelerator switch | Controls newly provisioned nodes from that pool. Read the NodePool’s configuration; cluster installation alone is insufficient. |
| NodeClass Image Accelerator setting | EKS and GKE also require the referenced NodeClass setting. AKS does not require a separate AKSNodeClass switch. |
For the current EKS/GKE/AKS setup prerequisites and new-node behavior, follow Set Up Image Accelerator. Do not extend that support claim to another provider because a generic capability flag is true. Metric meanings and hit-rate calculations are in Observability and Cost.
PVC monitoring and protection
MCP: list_cluster_pvcs; summary: get_cluster_overview.data.storage.
PVC monitoring is read-only: it does not resize a volume, create a PVC alert, or
change a StorageClass.
| Setting / field | Meaning and prerequisite |
|---|---|
| Disk Monitor | Enables collection of node filesystem and PVC data. If disabled, collection.disabledReason is diskMonitorSetting. |
| Data Protection Mode | Suppresses PVC identities and utilization uploads. The collection reports disabledReason: dataProtectionMode; asking for full detail cannot bypass it. |
items[].namespace, name, uid | Identify one Kubernetes PVC. Namespace and name alone do not distinguish a deleted-and-recreated claim; use UID when correlating history. |
items[].pvName, storageClassName | Returned with detail: full. A classless claim can have an empty storage class string; do not invent a default class. |
items[].lifecycleState | pending, bound, lost, terminating, or unknown. Separate from metric availability. |
items[].dataState | fresh, stale, or unavailable. A Bound PVC can still have unavailable usage metrics. |
See PVC Utilization for CSI/kubelet requirements and metric interpretation.
Organization configuration and notifications
MCP: get_organization_configuration with organization_id.
| MCP path | Type / meaning |
|---|---|
id, name | Organization identity. Use the ID returned by list_accessible_organizations, not a name guessed from a cluster. |
tags | Organization metadata tags; not Kubernetes labels or NodeClass cloud tags. |
allowSelfDeploy | Whether organization self-deployment is allowed; not proof that a cluster is installed or ready. |
alertConfig.disabledSend | Global alert-send suppression. Does not mean there are no active alerts. |
alertConfig.disabledTypeAlerts | Map from alert type to suppressed cluster IDs. Read active alerts separately from delivery configuration. |
userNotifyConfig.enable | Organization notification master switch, when present. |
userNotifyConfig.notificationConfigs[].name, enable, type | Destination identity, switch, and type (http, lark, or slack). Master and destination switches must be considered together. |
userNotifyConfig.notificationConfigs[].callbackConfigured | Whether a callback is configured. MCP intentionally does not return its URL or credentials. |
userNotifyConfig.notificationConfigs[].scope | eventNotify and alertNotifys maps control event/alert subscriptions; alert entries include enable and severity. Inspect the returned keys rather than guessing category names. |
marketplace[] | Marketplace subscription state associated with the organization; see the next section. |
An alert can be active while notifications are disabled. Conversely, a configured destination does not prove a message was delivered. Notification configuration reads do not send a test notification.
Marketplace and usage boundaries
marketplace[] includes provider/account identifiers and subscription state such
as provider, subscribeStatus, claimStatus, lifecycleStatus, usageStatus,
and lastMeteredHourStart. When available, commitment describes the current
cycle using status, displaySummary, committedCores, overageDimension,
cycleStartAt, cycleEndAt, totalCoreHours, usedCoveredCoreHours,
remainingCoreHours, and usedBillableCoreHours.
These are billing/subscription metadata, not cluster compute savings. Core-hours are a usage quantity, not currency; remaining hours can be unavailable. Do not derive a marketplace invoice, unused credit, or final amount due from these fields alone. New marketplace fields are version-dependent and require release confirmation before being described as universally available.
The Console’s detailed marketplace binding history, NA/WA account usage pages, and account security settings are not covered by dedicated MCP reads in the referenced tool catalog. TODO: keep those reads separate from organization configuration; never manufacture billing history from cluster cost estimates.
Members, invitations, and audit access
| Question | MCP tool and returned fields | Query / access rules |
|---|---|---|
| Who belongs to this organization? | list_organization_users: items[].id, name, email, avatar, role | filters.search matches user ID, not email/name. filters.roles: owner or member; sort by user_id or role. |
| Who has been invited? | list_organization_invitations: items[].id, organizationID, organizationName, inviter, email, role, status | Search email or invitation ID. Filter roles and statuses (pending, accepted, rejected, canceled); sort by id, email, role, or status. |
| Who changed something or called MCP? | list_organization_audit_logs: events[] | Organization owner access is required. Filter source (user/mcp), action, result (succeeded/partial/failed/denied), actor_id, search, and RFC3339 from/to. |
Audit reads default to the last seven days; from is inclusive and to
exclusive, with a maximum 365-day query span. Only event_time sorting is
supported (default descending). Use nextCursor with the unchanged query;
complete describes this page traversal, not whether every historic action was
retained. durationMs is milliseconds; changes[] gives field/before/after
information when recorded. Do not infer an absent secret from omitted values.
Member lists and invitations do not grant access. A pending invitation is not membership; reconnecting an OAuth client cannot promote a member to owner.
OAuth, API keys, and account settings
CloudPilot MCP uses OAuth and the read scope cloudpilot:mcp:read. Authorize
the intended account and organizations in the Console flow. Then call
list_accessible_organizations and use its organizationId, role, and
effective scope for subsequent requests.
An account-level connection can include several authorized organizations. A
cluster tool still requires explicit organization_id and cluster_id; an
organization outside the grant is not queryable simply because its ID is known.
Read scope does not authorize enabling optimization, updating a policy,
upgrading, or deleting resources.
An API key used by an installation or other API workflow is not the MCP OAuth credential: the MCP server rejects API-key authentication. This reference does not expose API-key values, refresh tokens, authorization headers, callback URLs, or MFA recovery data. The Console’s connected-client revoke controls and account MFA controls have no corresponding MCP read/write tools in the referenced catalog; use those Console pages for account security operations.
Scenario: an agent reports permission denied
- Check the account, authorized organization ID, and effective scope using
list_accessible_organizations; do not probe unrelated organizations. - For audit logs, verify organization owner access. If the user is a member, explain the access boundary rather than repeatedly requesting new tokens.
- Distinguish denied access, a tool absent from the deployed catalog, and an unavailable component. Do not “fix” a read failure by enabling features, generating a key, changing a role, or removing Data Protection Mode.
Safe configuration advice
Before suggesting any operational change, read the current value, provider, capability, and relevant installed version. State the expected effect and risk, which Console control changes it, and what should be observed afterwards. For example, re-enabling Disk Monitor should first produce a collecting state and then a fresh PVC snapshot; it cannot make an unsupported CSI driver report filesystem metrics. Keep execution separate from this read-only explanation.