OCM-3227: Add support for regionalized urls

connection.go

@@ -51,11 +51,12 @@ import (
 // Default values:
 const (
 	// #nosec G101
-	DefaultTokenURL     = authentication.DefaultTokenURL
-	DefaultClientID     = authentication.DefaultClientID
-	DefaultClientSecret = authentication.DefaultClientSecret
-	DefaultURL          = "https://api.openshift.com"
-	DefaultAgent        = "OCM-SDK/" + Version
+	DefaultTokenURL           = authentication.DefaultTokenURL
+	DefaultClientID           = authentication.DefaultClientID
+	DefaultClientSecret       = authentication.DefaultClientSecret
+	DefaultURL                = "https://api.openshift.com"
+	FormattedDefaultRegionURL = "https://api.%s.openshift.com"
+	DefaultAgent              = "OCM-SDK/" + Version
 )
 
 // DefaultScopes is the ser of scopes used by default:
@@ -232,6 +233,17 @@ func (b *ConnectionBuilder) URL(url string) *ConnectionBuilder {
 	return b.AlternativeURL("", url)
 }
 
+// Region builds the base URL of an API gateway based on an OCM region name. The default is
+// `https://api.%s.openshift.com`. Where `%s` is replaced by the region name.
+//
+// This method should be used in-lieu of URL when connecting to a regionalized API gateway.
+func (b *ConnectionBuilder) Region(region string) *ConnectionBuilder {
+	if b.err != nil {
+		return b
+	}
+	return b.AlternativeURL("", fmt.Sprintf(FormattedDefaultRegionURL, region))
+}
+
 // AlternativeURL sets an alternative base URL for the given path prefix. For example, to configure
 // the connection so that it sends the requests for the clusters management service to
 // `https://my.server.com`:
@@ -566,6 +578,7 @@ func (b *ConnectionBuilder) Load(source interface{}) *ConnectionBuilder {
 		URL              *string           `yaml:"url"`
 		AlternativeURLs  map[string]string `yaml:"alternative_urls"`
 		TokenURL         *string           `yaml:"token_url"`
+		Region           *string           `yaml:"region"`
 		User             *string           `yaml:"user"`
 		Password         *string           `yaml:"password"`
 		ClientID         *string           `yaml:"client_id"`
@@ -660,6 +673,11 @@ func (b *ConnectionBuilder) Load(source interface{}) *ConnectionBuilder {
 		b.MetricsSubsystem(*view.MetricsSubsystem)
 	}
 
+	// Regions:
+	if view.Region != nil {
+		b.Region(*view.Region)
+	}
+
 	return b
 }
 

examples/regionalized_list_clusters.go

@@ -0,0 +1,171 @@
+/*
+Copyright (c) 2023 Red Hat, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// This example shows how to retrieve the collection of clusters from a specific OCM region
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+
+	sdk "github.com/openshift-online/ocm-sdk-go"
+	cmv1 "github.com/openshift-online/ocm-sdk-go/clustersmgmt/v1"
+	"github.com/openshift-online/ocm-sdk-go/logging"
+)
+
+func main() {
+	// Create a context:
+	ctx := context.Background()
+
+	// Create a logger that has the debug level enabled:
+	logger, err := logging.NewGoLoggerBuilder().
+		Debug(true).
+		Build()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't build logger: %v\n", err)
+		os.Exit(1)
+	}
+
+	// USE CASE 1:
+	// You do not have the desired region ID and need to query the global region to find URL
+
+	// Create the global connection
+	token := os.Getenv("OCM_TOKEN")
+	globalConnection, err := sdk.NewConnectionBuilder().
+		Logger(logger).
+		Tokens(token).
+		Region("integration"). // Define the integration global region
+		BuildContext(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't build connection: %v\n", err)
+		os.Exit(1)
+	}
+	defer globalConnection.Close()
+
+	// Fetch the shards from the global region
+	response, err := globalConnection.Get().Path("/static/ocm-shards.json").SendContext(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't retrieve shards: %s\n", err)
+		os.Exit(1)
+	}
+
+	// Turn response into an interface with regions
+	data := response.Bytes()
+
+	// turn region bytes into a map
+	var regions map[string]interface{}
+	err = json.Unmarshal(data, &regions)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't unmarshal shards: %s\n", err)
+		os.Exit(1)
+	}
+
+	// Grab the singapore region URL
+	regionURL := regions["rh-singapore"].(map[string]interface{})["url"].(string)
+
+	// Build a regionalized connection based on the desired shard
+	connection, err := sdk.NewConnectionBuilder().
+		Logger(logger).
+		Tokens(token).
+		URL(fmt.Sprintf("https://%s", regionURL)). // Apply the region URL
+		BuildContext(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't build connection: %v\n", err)
+		os.Exit(1)
+	}
+	defer connection.Close()
+
+	// Get the client for the resource that manages the collection of clusters:
+	collection := connection.ClustersMgmt().V1().Clusters()
+
+	// Retrieve the list of clusters using pages of ten items, till we get a page that has less
+	// items than requests, as that marks the end of the collection:
+	size := 10
+	page := 1
+	for {
+		// Retrieve the page:
+		response, err := collection.List().
+			Search("name like 'my%'").
+			Size(size).
+			Page(page).
+			SendContext(ctx)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Can't retrieve page %d: %s\n", page, err)
+			os.Exit(1)
+		}
+
+		// Display the page:
+		response.Items().Each(func(cluster *cmv1.Cluster) bool {
+			fmt.Printf("%s - %s - %s\n", cluster.ID(), cluster.Name(), cluster.State())
+			return true
+		})
+
+		// Break the loop if the size of the page is less than requested, otherwise go to
+		// the next page:
+		if response.Size() < size {
+			break
+		}
+		page++
+	}
+
+	// USE CASE 2:
+	// You have a specific region ID and want to query that region directly
+
+	// Build the regionalized connection based on the desired region ID
+	connection, err = sdk.NewConnectionBuilder().
+		Logger(logger).
+		Tokens(token).
+		Region("aws.xcm.integration"). // Apply the region URL
+		BuildContext(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Can't build connection: %v\n", err)
+		os.Exit(1)
+	}
+	defer connection.Close()
+
+	collection = connection.ClustersMgmt().V1().Clusters()
+
+	// Retrieve the list of clusters using pages of ten items, till we get a page that has less
+	// items than requests, as that marks the end of the collection:
+	for {
+		// Retrieve the page:
+		response, err := collection.List().
+			Search("name like 'my%'").
+			Size(size).
+			Page(page).
+			SendContext(ctx)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Can't retrieve page %d: %s\n", page, err)
+			os.Exit(1)
+		}
+
+		// Display the page:
+		response.Items().Each(func(cluster *cmv1.Cluster) bool {
+			fmt.Printf("%s - %s - %s\n", cluster.ID(), cluster.Name(), cluster.State())
+			return true
+		})
+
+		// Break the loop if the size of the page is less than requested, otherwise go to
+		// the next page:
+		if response.Size() < size {
+			break
+		}
+		page++
+	}
+}