diff --git a/google/cloud/gkehub/v1beta1/membership.proto b/google/cloud/gkehub/v1beta1/membership.proto index 9830dd35..484fae3c 100644 --- a/google/cloud/gkehub/v1beta1/membership.proto +++ b/google/cloud/gkehub/v1beta1/membership.proto @@ -25,9 +25,12 @@ import "google/protobuf/field_mask.proto"; import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; +option csharp_namespace = "Google.Cloud.GkeHub.V1Beta1"; option go_package = "google.golang.org/genproto/googleapis/cloud/gkehub/v1beta1;gkehub"; option java_multiple_files = true; option java_package = "com.google.cloud.gkehub.v1beta1"; +option php_namespace = "Google\\Cloud\\GkeHub\\V1beta1"; +option ruby_package = "Google::Cloud::GkeHub::V1beta1"; // GKE Hub CRUD API for the Membership resource. // The Membership service is currently only available in the global location. @@ -43,7 +46,7 @@ service GkeHubMembershipService { option (google.api.method_signature) = "parent"; } - // Gets details of a single Membership. + // Gets the details of a Membership. rpc GetMembership(GetMembershipRequest) returns (Membership) { option (google.api.http) = { get: "/v1beta1/{name=projects/*/locations/*/memberships/*}" @@ -64,7 +67,7 @@ service GkeHubMembershipService { }; } - // Removes a single Membership. + // Removes a Membership. rpc DeleteMembership(DeleteMembershipRequest) returns (google.longrunning.Operation) { option (google.api.http) = { delete: "/v1beta1/{name=projects/*/locations/*/memberships/*}" @@ -89,7 +92,7 @@ service GkeHubMembershipService { }; } - // Generate the manifest for deployment of GKE connect agent. + // Generates the manifest for deployment of the GKE connect agent. rpc GenerateConnectManifest(GenerateConnectManifestRequest) returns (GenerateConnectManifestResponse) { option (google.api.http) = { get: "/v1beta1/{name=projects/*/locations/*/memberships/*}:generateConnectManifest" @@ -106,12 +109,13 @@ service GkeHubMembershipService { // GenerateExclusivityManifest generates the manifests to update the // exclusivity artifacts in the cluster if needed. - // Exclusivity artifacts include the membership customer resource definition - // (CRD) and the singleton membership custom resource (CR). - // Combined with ValidateExclusivity, exclusivity - // artifacts guarantee that a Kubernetes cluster is only registered to - // a single GKE Hub. - // The membership CRD is versioned, and may require conversion when the GKE + // + // Exclusivity artifacts include the Membership custom resource definition + // (CRD) and the singleton Membership custom resource (CR). Combined with + // ValidateExclusivity, exclusivity artifacts guarantee that a Kubernetes + // cluster is only registered to a single GKE Hub. + // + // The Membership CRD is versioned, and may require conversion when the GKE // Hub API server begins serving a newer version of the CRD and // corresponding CR. The response will be the converted CRD and CR if there // are any differences between the versions. @@ -129,45 +133,43 @@ message Membership { pattern: "projects/{project}/locations/{location}/memberships/{membership}" }; - // Specifies the infrastructure type that the API server represented by - // membership is running on. We use this field to determine pricing among - // other behavior. Each GKE distribution (on-GCP, on-Prem, on-X,...) - // will set a default while Attached Clusters - // customers will specify the type. If left unset, UNSPECIFIED is the - // default. + // Specifies the infrastructure type of a Membership. Infrastructure type is + // used by Hub to control infrastructure-specific behavior, including pricing. + // + // Each GKE distribution (on-GCP, on-Prem, on-X,...) will set this field + // automatically, but Attached Clusters customers should specify a type + // during registration. enum InfrastructureType { - // Default value for backward compatibility. Some Hub functionality may - // require users to set this value if left unspecified. + // No type was specified. Some Hub functionality may require a type be + // specified, and will not support Memberships with this value. INFRASTRUCTURE_TYPE_UNSPECIFIED = 0; - // OnPrem specifies Memberships running on infrastructure that is owned or - // operated by customers on private infrastructure. GKE Distributions like - // GKE-OnPrem and GKE-OnBareMetal will set this value at Membership creation - // time by default. + // Private infrastructure that is owned or operated by customer. This + // includes GKE distributions such as GKE-OnPrem and GKE-OnBareMetal. ON_PREM = 1; - // This value indicates the membership is running on public cloud - // infrastructure. + // Public cloud infrastructure. MULTI_CLOUD = 2; } - // Output only. The unique name of this domain resource in the format: - // `projects/[project_id]/locations/global/memberships/[membership_id]`. - // `membership_id` can only be set at creation time using the `membership_id` - // field in the creation request. `membership_id` must be a valid RFC 1123 - // compliant DNS label. In particular, it must be: + // Output only. The full, unique name of this Membership resource in the format + // `projects/*/locations/*/memberships/{membership_id}`, set during creation. + // + // `membership_id` must be a valid RFC 1123 compliant DNS label: + // // 1. At most 63 characters in length // 2. It must consist of lower case alphanumeric characters or `-` // 3. It must start and end with an alphanumeric character - // I.e. `membership_id` must match the regex: `[a-z0-9]([-a-z0-9]*[a-z0-9])?` - // with at most 63 characters. + // + // Which can be expressed as the regex: `[a-z0-9]([-a-z0-9]*[a-z0-9])?`, + // with a maximum length of 63 characters. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // Optional. GCP labels for this membership. map labels = 2 [(google.api.field_behavior) = OPTIONAL]; // Required. Description of this membership, limited to 63 characters. - // It must match the regex: `[a-zA-Z0-9][a-zA-Z0-9_\-\.\ ]*` + // Must match the regex: `[a-zA-Z0-9][a-zA-Z0-9_\-\.\ ]*` string description = 3 [(google.api.field_behavior) = REQUIRED]; // Type of resource represented by this Membership @@ -180,24 +182,27 @@ message Membership { MembershipState state = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; // Optional. How to identify workloads from this Membership. - // See the documentation on workload identity for more details: + // See the documentation on Workload Identity for more details: // https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity Authority authority = 9 [(google.api.field_behavior) = OPTIONAL]; - // Output only. Timestamp for when the Membership was created. + // Output only. When the Membership was created. google.protobuf.Timestamp create_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Output only. Timestamp for when the Membership was last updated. + // Output only. When the Membership was last updated. google.protobuf.Timestamp update_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Output only. Timestamp for when the Membership was deleted. + // Output only. When the Membership was deleted. google.protobuf.Timestamp delete_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; // Optional. An externally-generated and managed ID for this Membership. This ID may - // still be modified after creation but it is not recommended to do so. + // be modified after creation, but this is not recommended. For GKE clusters, + // external_id is managed by the Hub API and updates will be ignored. + // // The ID must match the regex: `[a-zA-Z0-9][a-zA-Z0-9_\-\.]*` + // // If this Membership represents a Kubernetes cluster, this value should be - // set to the UUID of the kube-system namespace object. + // set to the UID of the `kube-system` namespace object. string external_id = 10 [(google.api.field_behavior) = OPTIONAL]; // Output only. For clusters using Connect, the timestamp of the most recent connection @@ -211,128 +216,114 @@ message Membership { // resource with the same name is created, it gets a different unique_id. string unique_id = 12 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Optional. Specifies the infrastructure type that the API server represented by - // membership is running on. + // Optional. The infrastructure type this Membership is running on. InfrastructureType infrastructure_type = 13 [(google.api.field_behavior) = OPTIONAL]; } -// MembershipEndpoint contains the information to reach a member. +// MembershipEndpoint contains information needed to contact a Kubernetes API, +// endpoint and any additional Kubernetes metadata. message MembershipEndpoint { - // Optional. If this Membership is a Kubernetes API server hosted on GKE, this field - // will be populated and contain GKE-specific information. + // Optional. GKE-specific information. Only present if this Membership is a GKE cluster. GkeCluster gke_cluster = 4 [(google.api.field_behavior) = OPTIONAL]; - // Output only. For Memberships that point to Kubernetes Endpoints, this field provides - // useful metadata. + // Output only. Useful Kubernetes-specific metadata. KubernetesMetadata kubernetes_metadata = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Optional. A correctly registered cluster should have the Kubernetes resources - // applied to the clusters and settle at steady states. These resources are - // needed in order to: - // * Ensure that the cluster is exclusively registered to one and only one Hub - // Membership. - // * Propagate Workload Pool Information available in the Membership Authority - // field. - // * Ensure proper initial configuration of default Hub Features. + // Optional. The in-cluster Kubernetes Resources that should be applied for a correctly + // registered cluster, in the steady state. These resources: + // + // * Ensure that the cluster is exclusively registered to one and only one + // Hub Membership. + // * Propagate Workload Pool Information available in the Membership + // Authority field. + // * Ensure proper initial configuration of default Hub Features. KubernetesResource kubernetes_resource = 6 [(google.api.field_behavior) = OPTIONAL]; } -// KubernetesResource contains the YAML manifests and configs for Kubernetes -// resources of the Membership in the cluster. -// Upon CreateMembership: -// - The caller should provide membership_cr_manifest if a Membership CR -// exists in the cluster. -// - The caller should provide connect_version if they wish to also install -// the Connect agent. -// - The caller should then apply resources from the successful -// GetMembership request. -// Upon UpdateMembership: -// - The caller should provide membership_cr_manifest if a Membership CR -// exists in the cluster. -// - The caller should re-apply the resources from the returned Membership. +// KubernetesResource contains the YAML manifests and configuration for +// Membership Kubernetes resources in the cluster. After CreateMembership or +// UpdateMembership, these resources should be re-applied in the cluster. message KubernetesResource { - // Input only. The YAML representation of the Membership CR if already exists in the - // cluster. Leave empty if no Membership CR exists. - // The CR manifest will be used to validate that the cluster has not been - // registered with another Membership. For GKE clusters, the input from the - // caller will be ignored as Hub API server will directly fetch the - // Membership CR from the cluster. + // Input only. The YAML representation of the Membership CR. This field is ignored for GKE + // clusters where Hub can read the CR directly. + // + // Callers should provide the CR that is currently present in the cluster + // during CreateMembership or UpdateMembership, or leave this field empty if + // none exists. The CR manifest is used to validate the cluster has not been + // registered with another Membership. string membership_cr_manifest = 1 [(google.api.field_behavior) = INPUT_ONLY]; - // Output only. The additional Kubernetes resources that need to be applied to the cluster - // after the membership creation and every update. - // This field is only populated in the Membership returned after the - // long-running operation of Create/UpdateMembership finished, but not in - // standalone Get/ListMembership requests. - // To get the resource manifest after the initial registration, the caller - // could make an UpdateMembership call with an empty field mask. + // Output only. Additional Kubernetes resources that need to be applied to the cluster + // after Membership creation, and after every update. + // + // This field is only populated in the Membership returned from a successful + // long-running operation from CreateMembership or UpdateMembership. It is not + // populated during normal GetMembership or ListMemberships requests. To get + // the resource manifest after the initial registration, the caller should + // make a UpdateMembership call with an empty field mask. repeated ResourceManifest membership_resources = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Output only. The Kubernetes resources for installing GKE Connect agent. - // This field is only populated in the Membership returned after the - // long-running operation of Create/UpdateMembership finished, but not in - // standalone Get/ListMembership requests. - // To get the resource manifest after the initial registration, the caller - // could make an UpdateMembership call with an empty field mask. + // Output only. The Kubernetes resources for installing the GKE Connect agent + // + // This field is only populated in the Membership returned from a successful + // long-running operation from CreateMembership or UpdateMembership. It is not + // populated during normal GetMembership or ListMemberships requests. To get + // the resource manifest after the initial registration, the caller should + // make a UpdateMembership call with an empty field mask. repeated ResourceManifest connect_resources = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Optional. The options to generate Kubernetes resources other than the default - // value supplied by the Hub API. - // Empty or unset fields will use the default value. + // Optional. Options for Kubernetes resource generation. ResourceOptions resource_options = 4 [(google.api.field_behavior) = OPTIONAL]; } -// ResourceOptions represents the supported options for generating the -// Kubernetes resources. +// ResourceOptions represent options for Kubernetes resource generation. message ResourceOptions { - // Optional. The connect version to generate for connect_resources. If unset, default - // to the latest GKE Connect version. - // If set to a specific Connect version, the Connect resources of the - // version will be generated. If the version does not exist or is already - // out of support window, an INVALID_ARGUMENT error will be returned. + // Optional. The Connect agent version to use for connect_resources. Defaults to the + // latest GKE Connect version. The version must be a currently supported + // version, obsolete versions will be rejected. string connect_version = 1 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Use apiextensions/v1beta1 instead of apiextensions/v1 for - // CustomResourceDefinition resource. - // This option should be set for clusters with Kubernetes apiserver version + // Optional. Use `apiextensions/v1beta1` instead of `apiextensions/v1` for + // CustomResourceDefinition resources. + // This option should be set for clusters with Kubernetes apiserver versions // <1.16. bool v1beta1_crd = 2 [(google.api.field_behavior) = OPTIONAL]; } -// ResourceManifest represents a Kubernetes resource to be applied to +// ResourceManifest represents a single Kubernetes resource to be applied to // the cluster. message ResourceManifest { // YAML manifest of the resource. string manifest = 1; - // Specifies whether the resource provided in the manifest is cluster_scoped. - // If set to false, the assumption is that it is namespace scoped. - // This field is used for default REST mapper when applying the resource - // to a cluster. + // Whether the resource provided in the manifest is `cluster_scoped`. + // If unset, the manifest is assumed to be namespace scoped. + // + // This field is used for REST mapping when applying the resource in a + // cluster. bool cluster_scoped = 2; } -// GkeCluster represents a k8s cluster on GKE. +// GkeCluster contains information specific to GKE clusters. message GkeCluster { - // Immutable. Self-link of the GCP resource for the GKE cluster. - // For example: - // //container.googleapis.com/projects/my-project/locations/us-west1-a/clusters/my-cluster - // Using "zones" instead of "locations" is also valid. - // It can be at the most 1000 characters in length. + // Immutable. Self-link of the GCP resource for the GKE cluster. For example: + // + // //container.googleapis.com/projects/my-project/locations/us-west1-a/clusters/my-cluster + // + // Zonal clusters are also supported. string resource_link = 1 [(google.api.field_behavior) = IMMUTABLE]; } // KubernetesMetadata provides informational metadata for Memberships -// that are created from Kubernetes Endpoints (currently, these are equivalent -// to Kubernetes clusters). +// representing Kubernetes clusters. message KubernetesMetadata { // Output only. Kubernetes API server version string as reported by '/version'. string kubernetes_api_server_version = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. Node providerID as reported by the first node in the list of nodes on - // the Kubernetes endpoint. It should be noted that some Kubernetes platforms - // (like GKE-on-GCP) support zero-node clusters. For these platforms, the - // node_count will be zero and the node_provider_id will be empty. + // the Kubernetes endpoint. On Kubernetes platforms that support zero-node + // clusters (like GKE-on-GCP), the node_count will be zero and the + // node_provider_id will be empty. string node_provider_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. Node count as reported by Kubernetes nodes resources. @@ -352,75 +343,72 @@ message KubernetesMetadata { } // Authority encodes how Google will recognize identities from this Membership. -// A workload with a token from this oidc_issuer can call the IAM credentials -// API for the provided identity_namespace and identity_provider; the workload -// will receive a Google OAuth token that it can use for further API calls. // See the workload identity documentation for more details: // https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity message Authority { - // Optional. A JWT issuer URI. - // If set, then Google will attempt OIDC discovery on this URI, and allow - // valid OIDC tokens from this issuer to authenticate within the below - // identity namespace. + // Optional. A JSON Web Token (JWT) issuer URI. `issuer` must start with `https://` and + // be a valid URL with length <2000 characters. // - // This can be updated from a non-empty to empty value and vice-versa. - // But cannot be changed from one non-empty value to another. - // Setting to empty will disable Workload Identity. issuer should be a valid - // URL of length < 2000 that can be parsed, and must start with https://. + // If set, then Google will allow valid OIDC tokens from this issuer to + // authenticate within the workload_identity_pool. OIDC discovery will be + // performed on this URI to validate tokens from the issuer. + // + // Clearing `issuer` disables Workload Identity. `issuer` cannot be directly + // modified; it must be cleared (and Workload Identity disabled) before using + // a new issuer (and re-enabling Workload Identity). string issuer = 1 [(google.api.field_behavior) = OPTIONAL]; - // Output only. The name of the workload identity pool in which the above issuer will be - // recognized. There is a single Workload Identity Pool per Hub that is shared - // between all Memberships that belong to this Hub. For a Hub hosted in - // {PROJECT_ID}, the workload pool format is {PROJECT_ID}.hub.id.goog, + // Output only. The name of the workload identity pool in which `issuer` will be + // recognized. + // + // There is a single Workload Identity Pool per Hub that is shared + // between all Memberships that belong to that Hub. For a Hub hosted in + // {PROJECT_ID}, the workload pool format is `{PROJECT_ID}.hub.id.goog`, // although this is subject to change in newer versions of this API. string workload_identity_pool = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Output only. An identity provider that reflects this issuer in the workload identity + // Output only. An identity provider that reflects the `issuer` in the workload identity // pool. string identity_provider = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; } // State of the Membership resource. message MembershipState { - // Possible states of a Membership resources. + // Code describes the state of a Membership resource. enum Code { - // Not set. + // The code is not set. CODE_UNSPECIFIED = 0; - // CREATING indicates the cluster is being registered. + // The cluster is being registered. CREATING = 1; - // READY indicates the cluster is registered. + // The cluster is registered. READY = 2; - // DELETING indicates that the cluster is being unregistered. + // The cluster is being unregistered. DELETING = 3; - // UPDATING indicates the Membership is being updated. + // The Membership is being updated. UPDATING = 4; - // SERVICE_UPDATING indicates the Membership is being updated by - // the Hub Service. + // The Membership is being updated by the Hub Service. SERVICE_UPDATING = 5; } - // Output only. Code indicating the state of the Membership resource. + // Output only. The current state of the Membership resource. Code code = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Human readable description of the issue. - // This field is deprecated, and is never set by the Hub Service. + // This field is never set by the Hub Service. string description = 2 [deprecated = true]; - // The last update time of this state by the controllers - // This field is deprecated, and is never set by the Hub Service. + // This field is never set by the Hub Service. google.protobuf.Timestamp update_time = 3 [deprecated = true]; } // Request message for `GkeHubMembershipService.ListMemberships` method. message ListMembershipsRequest { - // Required. The parent in whose context the memberships are listed. The parent value - // is in the format: `projects/[project_id]/locations/global`. + // Required. The parent (project and location) where the Memberships will be listed. + // Specified in the format `projects/*/locations/*`. string parent = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. When requesting a 'page' of resources, `page_size` specifies number of @@ -433,36 +421,36 @@ message ListMembershipsRequest { // resources. string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Lists the Memberships that match the filter expression. A filter expression - // filters the resources listed in the response. The expression must be of - // the form ` ` where operators: `<`, `>`, `<=`, - // `>=`, - // `!=`, `=`, `:` are supported (colon `:` represents a HAS operator which is - // roughly synonymous with equality). can refer to a proto or JSON - // field, or a synthetic field. Field names can be camelCase or snake_case. + // Optional. Lists Memberships that match the filter expression, following the syntax + // outlined in https://google.aip.dev/160. // // Examples: - // - Filter by name: - // name = "projects/foo-proj/locations/global/membership/bar // - // - Filter by labels: - // - Resources that have a key called `foo` - // labels.foo:* - // - Resources that have a key called `foo` whose value is `bar` - // labels.foo = bar + // - Name is `bar` in project `foo-proj` and location `global`: // - // - Filter by state: - // - Members in CREATING state. - // state = CREATING + // name = "projects/foo-proj/locations/global/membership/bar" + // + // - Memberships that have a label called `foo`: + // + // labels.foo:* + // + // - Memberships that have a label called `foo` whose value is `bar`: + // + // labels.foo = bar + // + // - Memberships in the CREATING state: + // + // state = CREATING string filter = 4 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Field to use to sort the list. + // Optional. One or more fields to compare and use to sort the output. + // See https://google.aip.dev/132#ordering. string order_by = 5 [(google.api.field_behavior) = OPTIONAL]; } // Response message for the `GkeHubMembershipService.ListMemberships` method. message ListMembershipsResponse { - // The list of Memberships contained within the parent. + // The list of matching Memberships. repeated Membership resources = 1; // A token to request the next page of resources from the @@ -476,34 +464,36 @@ message ListMembershipsResponse { // Request message for `GkeHubMembershipService.GetMembership` method. message GetMembershipRequest { - // Required. The Membership resource name in the format: - // `projects/[project_id]/locations/global/memberships/[membership_id]` + // Required. The Membership resource name in the format + // `projects/*/locations/*/memberships/*`. string name = 1 [(google.api.field_behavior) = REQUIRED]; } // Request message for the `GkeHubMembershipService.CreateMembership` method. message CreateMembershipRequest { - // Required. The parent in whose context the membership is created. The parent value is - // in the format: `projects/[project_id]/locations/global`. + // Required. The parent (project and location) where the Memberships will be created. + // Specified in the format `projects/*/locations/*`. string parent = 1 [(google.api.field_behavior) = REQUIRED]; - // Required. Client chosen ID for the membership. The ID must be a valid RFC 1123 - // compliant DNS label. In particular, the ID must be: + // Required. Client chosen ID for the membership. `membership_id` must be a valid RFC + // 1123 compliant DNS label: + // // 1. At most 63 characters in length // 2. It must consist of lower case alphanumeric characters or `-` // 3. It must start and end with an alphanumeric character - // I.e. ID must match the regex: `[a-z0-9]([-a-z0-9]*[a-z0-9])?` with at most - // 63 characters. + // + // Which can be expressed as the regex: `[a-z0-9]([-a-z0-9]*[a-z0-9])?`, + // with a maximum length of 63 characters. string membership_id = 2 [(google.api.field_behavior) = REQUIRED]; - // Required. The resource to add. + // Required. The membership to create. Membership resource = 3 [(google.api.field_behavior) = REQUIRED]; } // Request message for `GkeHubMembershipService.DeleteMembership` method. message DeleteMembershipRequest { - // Required. The membership resource name in the format: - // `projects/[project_id]/locations/global/memberships/[membership_id]` + // Required. The Membership resource name in the format + // `projects/*/locations/*/memberships/*`. string name = 1 [(google.api.field_behavior) = REQUIRED]; } @@ -528,25 +518,23 @@ message UpdateMembershipRequest { // Request message for `GkeHubMembershipService.GenerateConnectManifest` // method. -// Bes ure to follow the practice in go/gkeconnect_agent_manifest before -// making changes to the proto. +// . message GenerateConnectManifestRequest { - // Required. The membership resource the connect agent is associated with. - // `projects/[project_id]/locations/global/memberships/[membership_id]`. + // Required. The Membership resource name the Agent will associate with, in the format + // `projects/*/locations/*/memberships/*`. string name = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. The connect agent to generate manifest for. ConnectAgent connect_agent = 2 [(google.api.field_behavior) = OPTIONAL]; - // Optional. The version to use for connect agent. - // If empty, the current default version will be used. + // Optional. The Connect agent version to use. Defaults to the most current version. string version = 3 [(google.api.field_behavior) = OPTIONAL]; // Optional. If true, generate the resources for upgrade only. Some resources - // (e.g. secrets) generated for installation will be excluded. + // generated only for installation (e.g. secrets) will be excluded. bool is_upgrade = 4 [(google.api.field_behavior) = OPTIONAL]; - // Optional. The registry to fetch connect agent image; default to + // Optional. The registry to fetch the connect agent image from. Defaults to // gcr.io/gkeconnect. string registry = 5 [(google.api.field_behavior) = OPTIONAL]; @@ -554,16 +542,16 @@ message GenerateConnectManifestRequest { bytes image_pull_secret_content = 6 [(google.api.field_behavior) = OPTIONAL]; } -// Response message for `GkeHubService.GenerateConnectManifest` -// method. +// GenerateConnectManifestResponse contains manifest information for +// installing/upgrading a Connect agent. message GenerateConnectManifestResponse { // The ordered list of Kubernetes resources that need to be applied to the // cluster for GKE Connect agent installation/upgrade. repeated ConnectAgentResource manifest = 1; } -// ConnectAgentResource represents a Kubernetes resource manifest for connect -// agent deployment. +// ConnectAgentResource represents a Kubernetes resource manifest for Connect +// Agent deployment. message ConnectAgentResource { // Kubernetes type of the resource. TypeMeta type = 1; @@ -572,7 +560,7 @@ message ConnectAgentResource { string manifest = 2; } -// TypeMeta is the type information needed for content unmarshalling of the +// TypeMeta is the type information needed for content unmarshalling of // Kubernetes resources in the manifest. message TypeMeta { // Kind of the resource (e.g. Deployment). @@ -584,51 +572,55 @@ message TypeMeta { // The information required from end users to use GKE Connect. message ConnectAgent { - // Optional. Deprecated. Do not set. - string name = 1 [(google.api.field_behavior) = OPTIONAL]; + // Do not set. + string name = 1 [deprecated = true]; - // Optional. URI of the proxy to reach gkeconnect.googleapis.com. - // The format must be in the form http(s)://{proxy_address}, - // depends on HTTP/HTTPS protocol supported by the proxy. This will direct - // connect agent's outbound traffic through a HTTP(S) proxy. + // Optional. URI of a proxy if connectivity from the agent to gkeconnect.googleapis.com + // requires the use of a proxy. Format must be in the form + // `http(s)://{proxy_address}`, depending on the HTTP/HTTPS protocol + // supported by the proxy. This will direct the connect agent's outbound + // traffic through a HTTP(S) proxy. bytes proxy = 2 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Namespace for GKE Connect agent resources. If empty, uses 'gke-connect'. + // Optional. Namespace for GKE Connect agent resources. Defaults to `gke-connect`. + // + // The Connect Agent is authorized automatically when run in the default + // namespace. Otherwise, explicit authorization must be granted with an + // additional IAM binding. string namespace = 3 [(google.api.field_behavior) = OPTIONAL]; } // The request to validate the existing state of the membership CR in the // cluster. message ValidateExclusivityRequest { - // Required. The desired parent collection of the membership to be created in the - // format: - // `projects/[project_id]/locations/global`. + // Required. The parent (project and location) where the Memberships will be created. + // Specified in the format `projects/*/locations/*`. string parent = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. The YAML of the membership CR in the cluster. Empty if the membership // CR does not exist. string cr_manifest = 2 [(google.api.field_behavior) = OPTIONAL]; - // Required. The membership name under the "name" that could be created if the - // validation succeed. The method only does validation in anticipation - // of a CreateMembership call. + // Required. The intended membership name under the `parent`. This method only does + // validation in anticipation of a CreateMembership call with the same name. string intended_membership = 3 [(google.api.field_behavior) = REQUIRED]; } // The response of exclusivity artifacts validation result status. message ValidateExclusivityResponse { - // The status.Code contains the validation result. As such, - // * OK means that exclusivity may be obtained if the manifest produced by - // GenerateExclusivityManifest can successfully be applied. - // * ALREADY_EXISTS means that the Membership CRD is already owned by another - // Hub. See status.message for more information when this occurs. + // The validation result. + // + // * `OK` means that exclusivity is validated, assuming the manifest produced + // by GenerateExclusivityManifest is successfully applied. + // * `ALREADY_EXISTS` means that the Membership CRD is already owned by + // another Hub. See `status.message` for more information. google.rpc.Status status = 1; } // The request to generate the manifests for exclusivity artifacts. message GenerateExclusivityManifestRequest { - // Required. The membership the cluster corresponds to in the format: - // `projects/[project_id]/locations/global/memberships/[membership_id]`. + // Required. The Membership resource name in the format + // `projects/*/locations/*/memberships/*`. string name = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. The YAML manifest of the membership CRD retrieved by