--- title: istio.mcp.v1alpha1 layout: protoc-gen-docs generator: protoc-gen-docs number_of_entries: 13 ---

This package defines the common, core types used by the Mesh Configuration Protocol.

## Services

### AggregatedMeshConfigService

The aggregated mesh configuration services allow a single management server, via a single gRPC stream, to deliver all API updates.

    rpc StreamAggregatedResources(MeshConfigRequest) returns (MeshConfigResponse)

StreamAggregatedResources provides the ability to carefully sequence updates across multiple resource types. A single stream is used with multiple independent MeshConfigRequest / MeshConfigResponses sequences multiplexed via the type URL.

    rpc IncrementalAggregatedResources(IncrementalMeshConfigRequest) returns (IncrementalMeshConfigResponse)

IncrementalAggregatedResources provides the ability to incrementally update the resources on the client. This supports the goal of scalability of MCP resources.

### ResourceSink

Service where the source is the gRPC client. The source is responsible for initiating connections and opening streams.

    rpc EstablishResourceStream(Resources) returns (RequestResources)

The source, acting as gRPC client, establishes a new resource stream with the sink. The sink sends RequestResources message to and receives Resources messages from the source.

### ResourceSource

Service where the sink is the gRPC client. The sink is responsible for initiating connections and opening streams.

    rpc EstablishResourceStream(RequestResources) returns (Resources)

The sink, acting as gRPC client, establishes a new resource stream with the source. The sink sends RequestResources message to and receives Resources messages from the source.

## Types

### IncrementalMeshConfigRequest

IncrementalMeshConfigRequest are be sent in 2 situations:

1. Initial message in a MCP bidirectional gRPC stream.

2. As a ACK or NACK response to a previous IncrementalMeshConfigResponse. In this case the responsenonce is set to the nonce value in the Response. ACK or NACK is determined by the absence or presence of errordetail.

Field | Type | Description
--- | --- | ---
`sinkNode` | `SinkNode` | The sink node making the request.
`typeUrl` | `string` | Type of the resource that is being requested, e.g. “type.googleapis.com/istio.io.networking.v1alpha3.VirtualService”.
`initialResourceVersions` | `map<string, string>` | When the IncrementalMeshConfigRequest is the first in a stream, the initialresourceversions must be populated. Otherwise, initialresourceversions must be omitted. The keys are the resources names of the MCP resources known to the MCP client. The values in the map are the associated resource level version info.
`responseNonce` | `string` | When the IncrementalMeshConfigRequest is a ACK or NACK message in response to a previous IncrementalMeshConfigResponse, the responsenonce must be the nonce in the IncrementalMeshConfigResponse. Otherwise responsenonce must be omitted.
`errorDetail` | `google.rpc.Status` | This is populated when the previous IncrementalMeshConfigResponses failed to update configuration. The message field in error_details provides the client internal exception related to the failure.

### IncrementalMeshConfigResponse

IncrementalMeshConfigResponses do not need to include a full snapshot of the tracked resources. Instead they are a diff to the state of a MCP client. Per resource versions allow servers and clients to track state at the resource granularity. An MCP incremental session is always in the context of a gRPC bidirectional stream. This allows the MCP server to keep track of the state of MCP clients connected to it.

In Incremental MCP the nonce field is required and used to pair IncrementalMeshConfigResponse to an IncrementalMeshConfigRequest ACK or NACK. Optionally, a response message level systemversioninfo is present for debugging purposes only.

Field | Type | Description
--- | --- | ---
`systemVersionInfo` | `string` | The version of the response data (used for debugging).
`resources` | `Resource[]` | The response resources wrapped in the common MCP Resource message. These are typed resources that match the type url in the IncrementalMeshConfigRequest.
`removedResources` | `string[]` | Resources names of resources that have be deleted and to be removed from the MCP Client. Removed resources for missing resources can be ignored.
`nonce` | `string` | The nonce provides a way for IncrementalMeshConfigRequests to uniquely reference an IncrementalMeshConfigResponse. The nonce is required.

### MeshConfigRequest

A MeshConfigRequest requests a set of versioned resources of the same type for a given client.

Field | Type | Description
--- | --- | ---
`versionInfo` | `string` | The versioninfo provided in the request messages will be the versioninfo received with the most recent successfully processed response or empty on the first request. It is expected that no new request is sent after a response is received until the client instance is ready to ACK/NACK the new configuration. ACK/NACK takes place by returning the new API config version as applied or the previous API config version respectively. Each type_url (see below) has an independent version associated with it.
`sinkNode` | `SinkNode` | The sink node making the request.
`typeUrl` | `string` | Type of the resource that is being requested, e.g. “type.googleapis.com/istio.io.networking.v1alpha3.VirtualService”.
`responseNonce` | `string` | The nonce corresponding to MeshConfigResponse being ACK/NACKed. See above discussion on version_info and the MeshConfigResponse nonce comment. This may be empty if no nonce is available, e.g. at startup.
`errorDetail` | `google.rpc.Status` | This is populated when the previous MeshConfigResponse failed to update configuration. The message field in error_details provides the client internal exception related to the failure. It is only intended for consumption during manual debugging, the string provided is not guaranteed to be stable across client versions.

### MeshConfigResponse

A MeshConfigResponse delivers a set of versioned resources of the same type in response to a MeshConfigRequest.

Field | Type | Description
--- | --- | ---
`versionInfo` | `string` | The version of the response data.
`resources` | `Resource[]` | The response resources wrapped in the common MCP Resource message.
`typeUrl` | `string` | Type URL for resources wrapped in the provided resources(s). This must be consistent with the type_url in the wrapper messages if resources is non-empty.
`nonce` | `string` | The nonce provides a way to explicitly ack a specific MeshConfigResponse in a following MeshConfigRequest. Additional messages may have been sent by client to the management server for the previous version on the stream prior to this MeshConfigResponse, that were unprocessed at response send time. The nonce allows the management server to ignore any further MeshConfigRequests for the previous version until a MeshConfigRequest bearing the nonce.

### Metadata

Metadata information that all resources within the Mesh Configuration Protocol must have.

Field | Type | Description
--- | --- | ---
`name` | `string` | Fully qualified name of the resource. Unique in context of a collection. The fully qualified name consists of a directory and basename. The directory identifies the resources location in a resource hierarchy. The basename identifies the specific resource name within the context of that directory. The directory and basename are composed of one or more segments. Segments must be valid DNS labels. “/” is the delimiter between segments The rightmost segment is the basename. All segments to the left of the basename form the directory. Segments moving towards the left represent higher positions in the resource hierarchy, similar to reverse DNS notation. e.g. /<org>/<team>/<subteam>/<resource basename> An empty directory indicates a resource that is located at the root of the hierarchy, e.g. /<globally scoped resource> On Kubernetes the resource hierarchy is two-levels: namespaces and cluster-scoped (i.e. global). Namespace resources fully qualified name is of the form: ”/<k8s namespace>/<k8s resource name>“ Cluster scoped resources are located at the root of the hierarchy and are of the form: ”/<k8s resource name>“
`createTime` | `google.protobuf.Timestamp` | The creation timestamp of the resource.
`version` | `string` | Resource version. This is used to determine when resources change across resource updates. It should be treated as opaque by consumers/sinks.
`labels` | `map<string, string>` | Map of string keys and values that can be used to organize and categorize resources within a collection.
`annotations` | `map<string, string>` | Map of string keys and values that can be used by source and sink to communicate arbitrary metadata about this resource.

### RequestResources

A RequestResource can be sent in two situations:

Initial message in an MCP bidirectional change stream as an ACK or NACK response to a previous Resources. In this case the responsenonce is set to the nonce value in the Resources. ACK/NACK is determined by the presence of errordetail.

- ACK (nonce!=“”,error_details==nil)
- NACK (nonce!=“”,error_details!=nil)
- New/Update request (nonce==“”,error_details ignored)

Field | Type | Description
--- | --- | ---
`sinkNode` | `SinkNode` | The sink node making the request.
`collection` | `string` | Type of resource collection that is being requested, e.g. istio/networking/v1alpha3/VirtualService k8s/<apiVersion>/<kind>
`initialResourceVersions` | `map<string, string>` | When the RequestResources is the first in a stream, the initialresourceversions must be populated. Otherwise, initialresourceversions must be omitted. The keys are the resources names of the MCP resources known to the MCP client. The values in the map are the associated resource level version info.
`responseNonce` | `string` | When the RequestResources is an ACK or NACK message in response to a previous RequestResources, the responsenonce must be the nonce in the RequestResources. Otherwise responsenonce must be omitted.
`errorDetail` | `google.rpc.Status` | This is populated when the previously received resources could not be applied The message field in error_details provides the source internal error related to the failure.
`incremental` | `bool` | Request an incremental update for the specified collection. The source may choose to honor this request or ignore and and provide a full-state update in the corresponding `Resource` response.

### Resource

Resource as transferred via the Mesh Configuration Protocol. Each resource is made up of common metadata, and a type-specific resource payload.

Field | Type | Description
--- | --- | ---
`metadata` | `Metadata` | Common metadata describing the resource.
`body` | `google.protobuf.Any` | The primary payload for the resource.

### Resources

Resources do not need to include a full snapshot of the tracked resources. Instead they are a diff to the state of a MCP client. Per resource versions allow sources and sinks to track state at the resource granularity. An MCP incremental session is always in the context of a gRPC bidirectional stream. This allows the MCP source to keep track of the state of MCP sink connected to it.

In Incremental MCP the nonce field is required and used to pair Resources to an RequestResources ACK or NACK.

Field | Type | Description
--- | --- | ---
`systemVersionInfo` | `string` | The version of the response data (used for debugging).
`collection` | `string` | Type of resource collection that is being requested, e.g. istio/networking/v1alpha3/VirtualService k8s/<apiVersion>/<kind>
`resources` | `Resource[]` | The response resources wrapped in the common MCP Resource message. These are typed resources that match the type url in the RequestResources message. When `incremental` is true, this contains an array of resources to add/update for the specified collection. This modifies the existing collection at the sink When `incremental` is false, this contains the full set of resources for the specified collection. This replaces any previously delivered resources.
`removedResources` | `string[]` | Names of resources that have been deleted and to be removed from the MCP sink node. Removed resources for missing resources can be ignored. When `incremental` is true, this contains an array of resource names to remove for the specified collection. This modifies the existing resource collection at the sink. When `incremental` is false, this field should be ignored.
`nonce` | `string` | Required. The nonce provides a way for RequestChange to uniquely reference a RequestResources.
`incremental` | `bool` | This resource response is an incremental update. The source should only send incremental updates if the sink requested them.

### SinkNode

Identifies a specific MCP sink node instance. The node identifier is presented to the resource source, which may use this identifier to distinguish per sink configuration for serving. This information is not authoritative. Authoritative identity should come from the underlying transport layer (e.g. rpc credentials).

Field | Type | Description
--- | --- | ---
`id` | `string` | An opaque identifier for the MCP node.
`annotations` | `map<string, string>` | Opaque annotations extending the node identifier.

### google.rpc.Status

The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. The error model is designed to be:

- Simple to use and understand for most users
- Flexible enough to meet unexpected needs

#### Overview

The `Status` message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of google.rpc.Code, but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers understand and resolve the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package `google.rpc` that can be used for common error conditions.

#### Language mapping

The `Status` message is the logical representation of the error model, but it is not necessarily the actual wire format. When the `Status` message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C.

#### Other uses

The error model and the `Status` message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments.

Example uses of this error model include:

- Partial errors. If a service needs to return partial errors to the client, it may embed the `Status` in the normal response to indicate the partial errors.

- Workflow errors. A typical workflow has multiple steps. Each step may have a `Status` message for error reporting.

- Batch operations. If a client uses batch request and batch response, the `Status` message should be used directly inside batch response, one for each error sub-response.

- Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the `Status` message.

- Logging. If some API errors are stored in logs, the message `Status` could be used directly after any stripping needed for security/privacy reasons.

Field | Type | Description
--- | --- | ---
`code` | `int32` | The status code, which should be an enum value of google.rpc.Code.
`message` | `string` | A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
`details` | `google.protobuf.Any[]` | A list of messages that carry the error details. There is a common set of message types for APIs to use.