AWS Go SDK Guide

This guide uses AWS SDK for Go v2 and S3. The application keeps using AWS request and response types; only the client endpoint changes.

Start a local adapter

This guide’s bounded example uses S3 backed by Google Cloud Storage:

Install or update the Tensor9 CLI

Install the customer CLI with Homebrew, then confirm the binary is available:

brew tap tensor9ine/tensor9
brew trust tensor9ine/tensor9
brew install tensor9
tensor9 --version

If tensor9 is already installed, run brew upgrade tensor9 instead of the install command.

Authenticate with Tensor9

A Tensor9 API key is required. Use the key issued during onboarding, or email [email protected] to request one for your organization. Do not share your account or key with another customer or organization.If your secret manager has already supplied T9_API_KEY, skip the prompt. Otherwise, enter your key at a hidden prompt in the terminal where you will run tensor9:

Bash
Zsh

set +x
IFS= read -r -s -p 'Tensor9 API key: ' T9_API_KEY
printf '\n'
export T9_API_KEY

set +x
IFS= read -r -s 'T9_API_KEY?Tensor9 API key: '
printf '\n'
export T9_API_KEY

Check that the variable is set without printing it, then verify your Tensor9 identity:

: "${T9_API_KEY:?Set T9_API_KEY before continuing}"
tensor9 whoami

Confirm that the reported identity belongs to the intended customer account. Do not continue if authentication fails or the account is wrong. Keep shell tracing disabled while using the key. Do not paste the key into commands, shell profiles, source files, screenshots or support messages.See Install and Authenticate for the planned license lifecycle, entitlements and credential boundaries.

Inspect the S3 to Google Cloud Storage mapping

Ask Tensor9 to describe the exact directed service mapping used by this guide:

tensor9 explain \
  -origin aws::1.0.0::s3 \
  -target google::1.0.0::gcs \
  -fmt Human

Read the supported S3 operations and Google Cloud Storage limitations before starting the process. The mapping is directional: this command describes S3 requests adapted to Google Cloud Storage, not the reverse direction.

Prepare Google Cloud access

Authenticate with Google Cloud using its standard Application Default Credentials chain. The adapter uses that identity when it calls Google Cloud Storage.Use a dedicated test project and narrowly scoped credentials. Do not put credentials in the command line, source code, or screenshots.

Start the S3 service adapter

Run the S3 to Google Cloud Storage adapter as a foreground process:

tensor9 adapt svc run \
  --origin aws::1.0.0::s3 \
  --backend google::1.0.0::gcs

Leave this terminal open. This is the current foreground launcher, not the pending Docker launcher for local development mode. It calls your actual target-cloud services; it is separate from the in-memory emulator. Acquisition and license renewal require Tensor9 authentication. Keep the endpoint local to your test.

Copy the listening endpoint

When the command reports its listening endpoint, copy that exact value into a second terminal:

export T9_CLOUD_ADAPTER_ENDPOINT="<endpoint printed by tensor9>"

Keep the endpoint local to the test unless you have deliberately configured network access and authentication for another machine.

Run one bounded S3 request

Continue with this page’s client or tool instructions. Point only S3 at T9_CLOUD_ADAPTER_ENDPOINT, then perform one operation whose Google Cloud Storage effect you can verify independently.Check both sides: read the S3-shaped response and inspect the native object or bucket in Google Cloud Storage. A successful client response alone does not prove that the target state is correct.

Stop the local adapter

Return to the first terminal and press Control-C. Confirm the process exits before deleting the test object or bucket with Google Cloud’s native client.If the request failed, preserve the request ID, adapter endpoint, S3 operation name, Google Cloud request ID, and any x-t9-explain-* receipt headers before stopping the process.

Choose how to set the endpoint

Set it for the process

export AWS_ENDPOINT_URL_S3="$T9_CLOUD_ADAPTER_ENDPOINT"

AWS SDK for Go v2 reads that service-specific setting during LoadDefaultConfig. Build the S3 client without assigning BaseEndpoint:

import (
    "context"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func newS3(ctx context.Context) (*s3.Client, error) {
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithSharedConfigProfile("adapter-test"),
    )
    if err != nil { return nil, err }

    client := s3.NewFromConfig(cfg, func(options *s3.Options) {
        options.UsePathStyle = true
    })
    return client, nil
}

Set it on one client

: "${T9_CLOUD_ADAPTER_ENDPOINT:?start the local adapter and copy its endpoint first}"

package main

import (
    "context"
    "io"
    "os"
    "strings"
    "time"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func newS3(ctx context.Context) (*s3.Client, error) {
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithSharedConfigProfile("adapter-test"),
    )
    if err != nil {
        return nil, err
    }

    endpoint := os.Getenv("T9_CLOUD_ADAPTER_ENDPOINT")
    return s3.NewFromConfig(cfg, func(options *s3.Options) {
        options.BaseEndpoint = aws.String(endpoint)
        options.UsePathStyle = true
    }), nil
}

Keep the endpoint in a client factory. Do not install a process-wide resolver that redirects unrelated AWS services unless every redirected service has a configured adapter. BaseEndpoint on the client takes precedence over AWS_ENDPOINT_URL_S3.

Verify an object lifecycle

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

client, err := newS3(ctx)
if err != nil { panic(err) }

bucket := os.Getenv("TEST_BUCKET")
key := "go/" + time.Now().UTC().Format("20060102T150405.000000000Z") + "-hello.txt"
body := "hello through Cloud Adapter\n"

_, err = client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: aws.String(bucket),
    Key: aws.String(key),
    Body: strings.NewReader(body),
    ContentType: aws.String("text/plain"),
})
if err != nil { panic(err) }

_, err = client.HeadObject(ctx, &s3.HeadObjectInput{Bucket: aws.String(bucket), Key: aws.String(key)})
if err != nil { panic(err) }

got, err := client.GetObject(ctx, &s3.GetObjectInput{Bucket: aws.String(bucket), Key: aws.String(key)})
if err != nil { panic(err) }
defer got.Body.Close()

actual, err := io.ReadAll(got.Body)
if err != nil { panic(err) }
if string(actual) != body { panic("downloaded bytes differ") }

_, err = client.DeleteObject(ctx, &s3.DeleteObjectInput{Bucket: aws.String(bucket), Key: aws.String(key)})
if err != nil { panic(err) }

In production, do not read unbounded object bodies into memory.

Classify failures before retrying

Use errors.As to distinguish a service response from a transport or context failure. Capture the Smithy operation error, service error code, HTTP status, and request ID when present. A context deadline after PutObject is an uncertain write; inspect target state before retrying.

Production checklist

Pin the Go v2 module versions you test.
Give every request an appropriate deadline.
Reuse clients and HTTP transports.
Test paginator termination and continuation tokens.
Verify path-style or virtual-host addressing for the deployed endpoint.
Compare native target state after writes.
Exercise one expected not-found response.

See the S3 service page, response headers, and testing guide.

Tensor9 Cloud Adapter

How It Works

Getting Started

Configuration

Deployment

Support

Amazon Web Services

Google Cloud

Microsoft Azure

Making Trade-offs

Tuning

Debugging

Testing

Guides

Reference

AWS Go SDK Guide

Start a local adapter

Choose how to set the endpoint

Set it for the process

Set it on one client

Verify an object lifecycle

Classify failures before retrying

Production checklist

​Start a local adapter

​Choose how to set the endpoint

​Set it for the process

​Set it on one client

​Verify an object lifecycle

​Classify failures before retrying

​Production checklist

Start a local adapter

Choose how to set the endpoint

Set it for the process

Set it on one client

Verify an object lifecycle

Classify failures before retrying

Production checklist