Oracle Cloud Infrastructure (OCI) Go SDK

To interact with an OCI service, follow these steps:

1. Create a Client: Use the service-specific constructor following the pattern New<ServiceName>ClientWithConfigurationProvider. Pass a ConfigurationProvider (like the one from common.DefaultConfigProvider()) to the constructor.
2. Call Service Methods: Most service methods accept a context.Context and a request struct (e.g., GetGroupRequest). These methods return a response struct and an error.

Example: Fetching a Group from the Identity service

import (
	"context"
	"fmt"
	"github.com/oracle/oci-go-sdk/v49/common"
	"github.com/oracle/oci-go-sdk/v49/identity"
)

func main() {
	config := common.DefaultConfigProvider()
	client, err := identity.NewIdentityClientWithConfigurationProvider(config)
	if err != nil {
	    panic(err)
	}

	id := "your_group_id"
	response, err := client.GetGroup(context.Background(), identity.GetGroupRequest{GroupId: &id})
	if err != nil {
	    panic(err)
	}

	fmt.Println("Group's name is:", response.Name)
}

Resource principals allow code running within a specific OCI resource (like an OCI Function) to act with its own identity and credentials. This enables the function to interact with other OCI services without requiring hardcoded user credentials.

To implement this, you must configure identity and access management (IAM) in two steps:

1. Define a Dynamic Group: Create a dynamic group that includes your function as a member based on specific attributes (like resource type and compartment).
2. Define a Policy: Grant the dynamic group specific permissions to access resources within your tenancy or compartment.

The example code in example/example_resource_principal_function is designed to be packaged into an OCI Functions container to demonstrate this pattern.

### Example dynamic-group rule for dynamic group fnfunc-example-compartment

ALL {resource.type = 'fnfunc', resource.compartment.name = 'example-compartment'}

### Policy statement for policy example-compartment/fnfunc-grant-reads

allow dynamic-group fnfunc-example-compartment to read all-resources in compartment example-compartment

The SDK provides mechanisms to retry operations that fail due to transient errors or eventual consistency.

Retry Precedence (Highest to Lowest)

1. Operation level (RequestMetadata.RetryPolicy)
2. Client level
3. Global level
4. Environment level default
5. Service level default

Default Retry Policy

• Attempts: 1 initial request + 7 retries (8 total).
• Strategy: Exponential backoff with jitter (base 1s, exponent 2, max 30s wait, 0-1000ms jitter).
• Retryable Errors: HTTP 409 (IncorrectState, LockConflict), 429, 500, 502, 503, 504, and client-side connection timeouts/exceptions.

Handling Eventual Consistency

For Identity service changes, use a policy that handles the 'eventually consistent window' (approx. 4 minutes). The common.DefaultRetryPolicy() automatically switches to an eventually consistent strategy if a recent change is detected. It will make up to 9 attempts and retry on specific 400/404/409 error codes.

// Use SDK's default retry policy for a single request
defaultRetryPolicy := common.DefaultRetryPolicy()
request.RequestMetadata = common.RequestMetadata{
	RetryPolicy: &defaultRetryPolicy,
}

// Or set it for all requests in a client
client.SetCustomClientConfiguration(common.CustomClientConfiguration{
	RetryPolicy: &defaultRetryPolicy,
})

// Or set it globally for all clients
common.GlobalRetry = &defaultRetryPolicy

Some OCI operations use polymorphic JSON, which the SDK models as interfaces.

• Requests: Pass a concrete struct that implements the required interface into the request object.
• Responses: Use type assertion on the response interface to access the underlying concrete type.

// 1. Polymorphic Request: Passing a concrete struct to an interface field
client, _ := identity.NewIdentityClientWithConfigurationProvider(common.DefaultConfigProvider())
rCreate := identity.CreateIdentityProviderRequest{}

// CreateSaml2IdentityProviderDetails implements the CreateIdentityProviderDetails interface
details := identity.CreateSaml2IdentityProviderDetails{}
details.CompartmentId = common.String(tenancyID)
details.Name = common.String("someName")

rCreate.CreateIdentityProviderDetails = details

// 2. Polymorphic Response: Type asserting the interface to the expected type
rRead := identity.GetIdentityProviderRequest{}
rRead.IdentityProviderId = common.String("aValidId")
response, err := client.GetIdentityProvider(context.Background(), rRead)

// Type assert the interface to the concrete type
provider := response.IdentityProvider.(identity.Saml2IdentityProvider)

To get started with the OCI Go SDK, you can initialize a service client using a configuration provider (like the default one) and then use that client to make API calls. The following example demonstrates how to create an identityClient and list availability domains in a tenancy.

import (
	"context"
	"fmt"

	"github.com/oracle/oci-go-sdk/v65/common"
	"github.com/oracle/oci-go-sdk/v65/identity"
)

func main() {
	c, err := identity.NewIdentityClientWithConfigurationProvider(common.DefaultConfigProvider())
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	// The OCID of the tenancy containing the compartment.
	tenancyID, err := common.DefaultConfigProvider().TenancyOCID()
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	request := identity.ListAvailabilityDomainsRequest{
		CompartmentId: &tenancyID,
	}

	r, err := c.ListAvailabilityDomains(context.Background(), request)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	fmt.Printf("List of available domains: %v", r.Items)
	return
}