solo-io · soloio-bot · Mar 6, 2025
diff --git a/api/gloo.solo.io/admin/v2/root_trust_policy.proto b/api/gloo.solo.io/admin/v2/root_trust_policy.proto
@@ -1,3 +1,54 @@
+// A RootTrustPolicy is used to designate the root of trust, including the trust domain and root
+// certificates used by one or more service meshes. With a RootTrustPolicy, you can set
+// set up an Istio root CA and use that root CA to automatically issue intermediate CA certificates
+// for all your workload clusters that make up your multicluster service mesh. Because all intermediate CA certificates are
+// derived from the same root, your workloads can securely talk to each other, even across cluster boundaries.
+// This approach is also referred to as federated trust.
+//
+// You have the option to fully or partially manage the Istio CA certificate lifecycle. The
+// option that is right for you depends on the type of environment that you have and the level
+// of control you want to have over the Istio CA certificate lifecycle.
+//
+// ## Examples
+//
+// The following example instructs {{% reuse "conrefs/snippets/policies/ov_fault_injection.md" %}} to 
+// create a self-signed root CA certificate that is valid for 730 days. 
+//
+// ```yaml
+// apiVersion: admin.gloo.solo.io/v2
+// kind: RootTrustPolicy
+// metadata:
+//  name: root-trust-policy
+//  namespace: gloo-mesh
+// spec:
+//   config:
+//     mgmtServerCa:
+//       generated:
+//         ttlDays: 730
+// ```
+//
+// To bring your own root CA certificate, store the root CA credentials in a Kubernetes secret. Then,
+// reference this secret in your RootTrustPolicy. 
+//
+// ```yaml
+// apiVersion: admin.gloo.solo.io/v2
+// kind: RootTrustPolicy
+// metadata:
+//   name: istio-ingressgateway
+//   namespace: gloo-mesh
+// spec:
+//   config:
+//     mgmtServerCa:
+//       secretRef:
+//         name: my-root-trust-cert
+//         namespace: gloo-mesh
+// ```
+//
+// {{% alert %}}
+// Creating a RootTrustPoliy resource triggers the renewal of Istio certificates.
+// If your service mesh uses sidecars, you must restart your applications
+// to apply the latest certificate.
+// {{% /alert %}}
 syntax = "proto3";
 
 package admin.gloo.solo.io;
@@ -14,8 +65,6 @@ option (extproto.equal_all) = true;
 option (extproto.hash_all) = true;
 option (extproto.clone_all) = true;
 
-// RootTrustPolicy is used to designate the root of trust, including the trust domain and root certificates used by one or more service meshes.
-// A shared RootTrustPolicy is currently required to support communication between workloads and destinations running in different meshes. In the future Gloo Mesh will support cross-mesh connectivity using a Limited Trust model (where participating meshes are permitted to use separate roots of trust).
 message RootTrustPolicySpec {
 
   // select the meshes where the root of trust will be applied.
@@ -52,10 +101,12 @@ message RootTrustPolicySpec {
       // Specify the source of the Root CA data which Gloo Mesh will use for the RootTrustPolicy.
       oneof ca_source {
 
-        // Generate a self-signed root certificate with the given options.
+        // Generate a self-signed root certificate with the given options. By default, the root CA
+        // is valid for 1 year.
         .tls.security.policy.gloo.solo.io.CommonCertOptions generated = 1;
 
-        // Name of a Kubernetes Secret in the same namespace as the RootTrustPolicy containing the root certificate authority.
+        // The name of a Kubernetes secret in the same namespace as the RootTrustPolicy that contains the
+        // root certificate authority.
         // Provided certificates must conform to a specified format, [documented here]({{< link path="/setup/prod/certs/relay/" >}}).
         .core.skv2.solo.io.ObjectRef secret_ref = 2;
 

diff --git a/api/gloo.solo.io/admin/v2/workspace_settings.proto b/api/gloo.solo.io/admin/v2/workspace_settings.proto
@@ -253,7 +253,7 @@ message WorkspaceSettingsSpec {
     repeated EastWestGatewaySelector east_west_gateways = 3;
 
     // Optional: Virtual destination client mode determines how VirtualDestinations will be translated.
-    // If nil, the default value of auto mode will be used. Any configuration here can be overriden
+    // If nil, the default value of auto mode will be used. Any configuration here can be overridden
     // on any individual virtual destination. The settings defined here apply to both user-provided
     // VirtualDestinations and those generated internally when federation is enabled.
     .common.gloo.solo.io.ClientMode virtual_dest_client_mode = 4;
@@ -276,6 +276,7 @@ message WorkspaceSettingsSpec {
       // When enabled, trim the outbound config from the Istio sidecar proxies for any destination outside the workspace.
       // The sidecar proxies keep the configuration for all destinations in the workspace (including imported destinations).
       // To trim proxies for specific destinations with the workspace, you can use the `TrimProxyConfigPolicy` instead.
+      // {{< reuse "conrefs/snippets/policies/trim-proxy-workloads-limit.md" >}}
       google.protobuf.BoolValue trim_proxy_config = 2;
 
       // Optional: When NetworkPolicy translation is enabled, by default, all available layers will be used to enforce Service Isolation.

diff --git a/api/gloo.solo.io/apimanagement/v2/api_doc.proto b/api/gloo.solo.io/apimanagement/v2/api_doc.proto
@@ -4,7 +4,6 @@
 // The ApiDoc type is used to represent different types of API schema specification languages:
 // - OpenAPI
 // - gRPC
-// - GraphQL
 syntax = "proto3";
 
 package apimanagement.gloo.solo.io;
@@ -46,6 +45,8 @@ message ApiDocSpec {
     // The gRPC schema specification language. Specify only one schema type.
     GrpcSchema grpc = 2;
 
+    // <b>Unsupported</b>: The GraphQL integration is no longer supported.
+    //
     // The graphQL schema specification language. Specify only one schema type.
     GraphQLSchema graphql = 3;
   }
@@ -83,18 +84,9 @@ message ApiDocSpec {
     string inline_string = 1;
   }
 
-  // A complete gRPC schema describing the API.
+  // <b>Unsupported</b>: The GraphQL integration is no longer supported.
   //
-  // ## Example
-// In this gRPC example for a basic user service app,
-  // the base64-encoded descriptor includes a set of fields that are defined
-  // for various queries, such as `UserSearch` and `UserByCountry`. For detailed
-  // information about the settings in this example, see
-  // [gRPC schema](https://docs.solo.io/gloo-mesh-gateway/2.4.x/graphql/resolvers/resolved/resolver_grpc/)
-  // in the GraphQL integration documentation.
-  // ```yaml
-  // {{% readfile file="static/content/examples/generated/int/graphql_routes/cluster-1/api-doc_bookinfo_grpc-schema.yaml" %}}
-  // ```
+  // A complete gRPC schema describing the API.
   message GrpcSchema {
     // Protobuf descriptors that represent the gRPC services provided by your API, encoded in base64.
     // For more information, see the
@@ -103,20 +95,13 @@ message ApiDocSpec {
 
   }
 
+  // <b>Unsupported</b>: The GraphQL integration is no longer supported.
+  //
   // Provide a schema definition in GraphQL SDL format.
   // The GraphQL schema also has logging options for logging sensitive
   // request-related information, and schema extension configuration such as
   // custom type definitions. For more information about the different schema features,
   // see the [GraphQL documentation](https://graphql.org/learn/schema/).
-  //
-  // ## Example
-// In this GraphQL example for the Bookinfo sample app, a query type and object
-  // types are defined. For detailed information about the settings in this example, see
-  // [Example GraphQL ApiDoc](https://docs.solo.io/gloo-mesh-gateway/2.4.x/graphql/apidoc/#example-graphql-apidoc)
-  // in the GraphQL integration documentation.
-  // ```yaml
-  // {{% readfile file="static/content/examples/generated/int/graphql_proxied_introspection/cluster-1/api-doc_bookinfo_music-schema.yaml" %}}
-  // ```
   message GraphQLSchema {
     // Required: The GraphQL schema definition. Root-level query and mutation
     // types are supported, and you must define at least a query type.

diff --git a/api/gloo.solo.io/apimanagement/v2/graphql_schema.proto b/api/gloo.solo.io/apimanagement/v2/graphql_schema.proto
@@ -52,7 +52,7 @@ message GraphQLSchemaSpec {
     Options options = 2;
 
     // Set additional options on the references to GraphQLResolverMap resources.
-    // As as simple example for the `mex_depth` option, if the schema is
+    // As a simple example for the `max_depth` option, if the schema is
     // ```gql
     // type Query {
     //   employee: Employee

diff --git a/api/gloo.solo.io/networking/v2/virtual_gateway.proto b/api/gloo.solo.io/networking/v2/virtual_gateway.proto
@@ -223,8 +223,10 @@ message VirtualGatewaySpec {
     message HTTPServer {
 
     }
-
-    // @exclude TODO: TCPServer
+
+    // Serve TCP routes for RouteTables that select this gateway.
+    // Make sure to open a TCP port on the backing Istio ingress gateway,
+    // which might require upgrading your IstioLifecycleManager or Helm installation.
     message TCPServer {
 
     }

diff --git a/api/gloo.solo.io/policy/v2/resilience/failover_policy.proto b/api/gloo.solo.io/policy/v2/resilience/failover_policy.proto
@@ -69,10 +69,6 @@ message FailoverPolicySpec {
 
   // Select the destinations to apply the policy to by using labels.
   // If empty, the policy applies to all destinations in the workspace.
-  // {{< alert context="info" >}}
-  // The destinations can be Kubernetes services or virtual destinations. 
-  // Note that external services are not supported as destinations with this policy.
-  // {{< /alert >}}
   repeated .common.gloo.solo.io.DestinationSelector apply_to_destinations = 1;
 
   // The details of the failover policy to apply to the selected virtual destinations.

diff --git a/api/gloo.solo.io/policy/v2/resilience/listener_connection_policy.proto b/api/gloo.solo.io/policy/v2/resilience/listener_connection_policy.proto
@@ -18,7 +18,7 @@ option (extproto.clone_all) = true;
 // ListenerConnectionPolicy is used to set configuration for gateway listeners.
 //
 // ```
-// apiVersion: trafficcontrol.policy.gloo.solo.io/v2
+// apiVersion: resilience.policy.gloo.solo.io/v2
 // kind: ListenerConnectionPolicy
 // metadata:
 //   name: my-policy

diff --git a/api/gloo.solo.io/policy/v2/resilience/trim_proxy_config_policy.proto b/api/gloo.solo.io/policy/v2/resilience/trim_proxy_config_policy.proto
@@ -1,4 +1,5 @@
 // {{% reuse "conrefs/snippets/policies/ov_trimproxy.md" %}}
+// {{< reuse "conrefs/snippets/policies/trim-proxy-workloads-limit.md" >}}
 // For more information, see the [Trim proxy config guide](https://docs.solo.io/gloo-mesh-enterprise/latest/resiliency/trim-proxy-config/trim-proxy-policy/).
 // 
 // ## Example
@@ -29,6 +30,7 @@ option (extproto.clone_all) = true;
 message TrimProxyConfigPolicySpec {
 
   // Select the workloads for the policy to trim the Istio sidecar config. If omitted, all workloads are selected.
+  // {{< reuse "conrefs/snippets/policies/trim-proxy-workloads-limit.md" >}}
   repeated .common.gloo.solo.io.WorkloadSelector apply_to_workloads = 1;
 
 

diff --git a/api/gloo.solo.io/policy/v2/security/access_policy.proto b/api/gloo.solo.io/policy/v2/security/access_policy.proto
@@ -176,9 +176,9 @@ option (extproto.clone_all) = true;
 // Specifications for the policy.
 message AccessPolicySpec {
 
-  // Destinations to apply the policy to. 
+  // Destinations to apply the policy to.
   // Note that virtual destinations are not supported as destinations with this policy.
-  // If `applyToWorkloads` is non-empty, this field is ignored. 
+  // If `applyToWorkloads` is non-empty, this field is ignored.
   // If this field and `applyToWorkloads` are both empty,
   // the policy applies to all ports on all destinations in the workspace.
   // {{< alert context="info" >}}
@@ -187,7 +187,7 @@ message AccessPolicySpec {
   repeated .common.gloo.solo.io.DestinationSelector apply_to_destinations = 1;
 
   // Workloads to apply the policy to. For security reasons,
-  // this field is prefered over `applyToDestinations`. If an empty selector is 
+  // this field is preferred over `applyToDestinations`. If an empty selector is
   // provided in the list, the policy applies to all workloads in a namespace, cluster,
   // and workspace that are available in the parent object's workspace.
   repeated NamespaceWorkloadSelector apply_to_workloads = 3;

diff --git a/api/gloo.solo.io/policy/v2/security/jwt_policy.proto b/api/gloo.solo.io/policy/v2/security/jwt_policy.proto
@@ -106,7 +106,8 @@ message JWTPolicySpec {
   // If omitted and the policy selects a destination, the policy does not apply to any routes.
   repeated .common.gloo.solo.io.RouteSelector apply_to_routes = 1;
 
-  // Select the destinations where the policy will be applied. Only Kubernetes services are supported.
+  // Select the destinations where the policy will be applied.
+  // {{< reuse "conrefs/snippets/field-desc/dest-no-vdest.md" >}}
   // By default if omitted, the policy does not apply to any destinations.
   // If empty (`{}`), the policy applies to all destinations in the workspace.
   repeated .common.gloo.solo.io.DestinationSelector apply_to_destinations = 3;

diff --git a/api/gloo.solo.io/policy/v2/security/tls/ca_options.proto b/api/gloo.solo.io/policy/v2/security/tls/ca_options.proto
@@ -119,7 +119,7 @@ enum CertificateRotationStrategy {
   NONE = 1;
 }
 
-// CertificateRotationCondition represents a timesptamped snapshot of the certificate
+// CertificateRotationCondition represents a timestamped snapshot of the certificate
 // rotation workflow. This is used to keep track of the steps which have been completed
 // thus far.
 message CertificateRotationCondition {

diff --git a/api/gloo.solo.io/policy/v2/trafficcontrol/mirror_policy.proto b/api/gloo.solo.io/policy/v2/trafficcontrol/mirror_policy.proto
@@ -50,6 +50,6 @@ message MirrorPolicyReport {
   // The status of the resource in each workspace that it exists in.
   map<string, .common.gloo.solo.io.Report> workspaces = 1;
 
-  // A list of references to all rotues selected by the policy.
+  // A list of references to all routes selected by the policy.
   repeated .common.gloo.solo.io.RouteReference selected_routes = 2;
 }
diff --git a/api/gloo.solo.io/policy/v2/trafficcontrol/ratelimit_policy.proto b/api/gloo.solo.io/policy/v2/trafficcontrol/ratelimit_policy.proto
@@ -29,8 +29,7 @@ message RateLimitPolicySpec {
   repeated .common.gloo.solo.io.RouteSelector apply_to_routes = 1;
 
   // Select the destinations where the policy will be applied.
-  // Note that rate limit outputs are only translated for destinations that are Kubernetes services.
-  // External services and virtual destinations are not supported as destinations with this policy.
+  // {{< reuse "conrefs/snippets/field-desc/dest-no-vdest.md" >}}
   // If empty, the rate limit policy applies to all destinations in the workspace.
   // If the destination selector is empty but the route selector is set, no rate limits are applied on destinations, only on routes.
   repeated .common.gloo.solo.io.DestinationSelector apply_to_destinations = 2;

diff --git a/api/gloo.solo.io/policy/v2/trafficcontrol/transformation_policy.proto b/api/gloo.solo.io/policy/v2/trafficcontrol/transformation_policy.proto
@@ -36,7 +36,7 @@ message TransformationPolicySpec {
 
     message RequestTransformation {
 
-      // If set to **true**, recalculate the routing destination and select a new route for transformed requests. 
+      // If set to **true**, recalculate the routing destination and select a new route for transformed requests.
       // For example, if you have a request that is transformed to match a new route, the new route is selected 
       // when calculating the routing destination. The default value is **false**. 
       bool recalculate_routing_destination = 1;

diff --git a/client-go/admin.gloo.solo.io/v2/root_trust_policy.pb.go b/client-go/admin.gloo.solo.io/v2/root_trust_policy.pb.go
@@ -1,3 +1,55 @@
+// A RootTrustPolicy is used to designate the root of trust, including the trust domain and root
+// certificates used by one or more service meshes. With a RootTrustPolicy, you can set
+// set up an Istio root CA and use that root CA to automatically issue intermediate CA certificates
+// for all your workload clusters that make up your multicluster service mesh. Because all intermediate CA certificates are
+// derived from the same root, your workloads can securely talk to each other, even across cluster boundaries.
+// This approach is also referred to as federated trust.
+//
+// You have the option to fully or partially manage the Istio CA certificate lifecycle. The
+// option that is right for you depends on the type of environment that you have and the level
+// of control you want to have over the Istio CA certificate lifecycle.
+//
+// ## Examples
+//
+// The following example instructs {{% reuse "conrefs/snippets/policies/ov_fault_injection.md" %}} to
+// create a self-signed root CA certificate that is valid for 730 days.
+//
+// ```yaml
+// apiVersion: admin.gloo.solo.io/v2
+// kind: RootTrustPolicy
+// metadata:
+//  name: root-trust-policy
+//  namespace: gloo-mesh
+// spec:
+//   config:
+//     mgmtServerCa:
+//       generated:
+//         ttlDays: 730
+// ```
+//
+// To bring your own root CA certificate, store the root CA credentials in a Kubernetes secret. Then,
+// reference this secret in your RootTrustPolicy.
+//
+// ```yaml
+// apiVersion: admin.gloo.solo.io/v2
+// kind: RootTrustPolicy
+// metadata:
+//   name: istio-ingressgateway
+//   namespace: gloo-mesh
+// spec:
+//   config:
+//     mgmtServerCa:
+//       secretRef:
+//         name: my-root-trust-cert
+//         namespace: gloo-mesh
+// ```
+//
+// {{% alert %}}
+// Creating a RootTrustPoliy resource triggers the renewal of Istio certificates.
+// If your service mesh uses sidecars, you must restart your applications
+// to apply the latest certificate.
+// {{% /alert %}}
+
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.26.0
@@ -26,8 +78,6 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
-// RootTrustPolicy is used to designate the root of trust, including the trust domain and root certificates used by one or more service meshes.
-// A shared RootTrustPolicy is currently required to support communication between workloads and destinations running in different meshes. In the future Gloo Mesh will support cross-mesh connectivity using a Limited Trust model (where participating meshes are permitted to use separate roots of trust).
 type RootTrustPolicySpec struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
@@ -337,12 +387,14 @@ type isRootTrustPolicySpec_Config_MgmtServerCertificateAuthority_CaSource interf
 }
 
 type RootTrustPolicySpec_Config_MgmtServerCertificateAuthority_Generated struct {
-	// Generate a self-signed root certificate with the given options.
+	// Generate a self-signed root certificate with the given options. By default, the root CA
+	// is valid for 1 year.
 	Generated *tls.CommonCertOptions `protobuf:"bytes,1,opt,name=generated,proto3,oneof"`
 }
 
 type RootTrustPolicySpec_Config_MgmtServerCertificateAuthority_SecretRef struct {
-	// Name of a Kubernetes Secret in the same namespace as the RootTrustPolicy containing the root certificate authority.
+	// The name of a Kubernetes secret in the same namespace as the RootTrustPolicy that contains the
+	// root certificate authority.
 	// Provided certificates must conform to a specified format, [documented here]({{< link path="/setup/prod/certs/relay/" >}}).
 	SecretRef *v1.ObjectRef `protobuf:"bytes,2,opt,name=secret_ref,json=secretRef,proto3,oneof"`
 }

diff --git a/client-go/admin.gloo.solo.io/v2/workspace_settings.pb.go b/client-go/admin.gloo.solo.io/v2/workspace_settings.pb.go