CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com--aws--aws-sdk-go-v2

AWS SDK for Go v2 with 130+ service clients, Request/Send pattern, and context support.

Overview
Eval results
Files

credentials.mddocs/reference/

Credentials Providers

The SDK supports multiple credential providers. All implement the aws.CredentialsProvider interface.

CredentialsProvider Interface

// From package github.com/aws/aws-sdk-go-v2/aws
type CredentialsProvider interface {
    Retrieve() (Credentials, error)
    IsExpired() bool
}

type Credentials struct {
    AccessKeyID     string
    SecretAccessKey string
    SessionToken    string  // empty for long-term credentials
    Source          string  // provider name
    CanExpire       bool
    Expires         time.Time
}

func (v Credentials) Expired() bool
func (v Credentials) HasKeys() bool

Static Credentials

Import: github.com/aws/aws-sdk-go-v2/aws

Hardcode credentials. Credentials never expire.

const StaticCredentialsProviderName = "StaticCredentialsProvider"

type StaticCredentialsProvider struct {
    Value Credentials
}

func NewStaticCredentialsProvider(key, secret, session string) StaticCredentialsProvider
func (s StaticCredentialsProvider) Retrieve() (Credentials, error)
func (s StaticCredentialsProvider) IsExpired() bool

var ErrStaticCredentialsEmpty = awserr.New("EmptyStaticCreds", "static credentials are empty", nil)
cfg.Credentials = aws.NewStaticCredentialsProvider(
    "AKIAIOSFODNN7EXAMPLE",
    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "",
)

Chain Provider

Import: github.com/aws/aws-sdk-go-v2/aws

Tries each provider in order until one returns valid credentials.

type ChainProvider struct {
    SafeCredentialsProvider
    Providers []CredentialsProvider
}

func NewChainProvider(providers []CredentialsProvider) *ChainProvider
cfg.Credentials = aws.NewChainProvider([]aws.CredentialsProvider{
    aws.NewStaticCredentialsProvider(os.Getenv("AWS_ACCESS_KEY_ID"), os.Getenv("AWS_SECRET_ACCESS_KEY"), ""),
    ec2rolecreds.NewProvider(ec2metadata.New(cfg)),
})

EC2 Instance Role Credentials

Import: github.com/aws/aws-sdk-go-v2/aws/ec2rolecreds

Retrieves credentials from the EC2 Instance Metadata Service.

const ProviderName = "EC2RoleProvider"

type Provider struct {
    aws.SafeCredentialsProvider
    Client       *ec2metadata.EC2Metadata
    ExpiryWindow time.Duration  // refresh this long before actual expiry
}

func NewProvider(client *ec2metadata.EC2Metadata) *Provider
import (
    "github.com/aws/aws-sdk-go-v2/aws/ec2metadata"
    "github.com/aws/aws-sdk-go-v2/aws/ec2rolecreds"
)

metaClient := ec2metadata.New(cfg)
provider := ec2rolecreds.NewProvider(metaClient)
provider.ExpiryWindow = 10 * time.Minute

cfg.Credentials = provider

STS Assume Role Credentials

Import: github.com/aws/aws-sdk-go-v2/aws/stscreds

Assumes an IAM role via STS and returns temporary credentials.

const ProviderName = "AssumeRoleProvider"

var DefaultDuration = 15 * time.Minute

type AssumeRoleProvider struct {
    aws.SafeCredentialsProvider
    Client           AssumeRoler
    RoleARN          string
    RoleSessionName  string
    Duration         time.Duration    // default: 15 minutes
    ExternalID       *string
    Policy           *string
    SerialNumber     *string          // MFA device serial
    TokenCode        *string          // static MFA token (for short-lived use)
    TokenProvider    func() (string, error)  // dynamic MFA token function
    ExpiryWindow     time.Duration    // refresh before expiry
}

func NewAssumeRoleProvider(client AssumeRoler, roleARN string) *AssumeRoleProvider

type AssumeRoler interface {
    AssumeRoleRequest(input *sts.AssumeRoleInput) sts.AssumeRoleRequest
}

// Reads MFA token from stdin
func StdinTokenProvider() (string, error)
import (
    "github.com/aws/aws-sdk-go-v2/aws/stscreds"
    "github.com/aws/aws-sdk-go-v2/service/sts"
)

// Basic assume role
stsSvc := sts.New(cfg)
provider := stscreds.NewAssumeRoleProvider(stsSvc, "arn:aws:iam::123456789012:role/MyRole")
cfg.Credentials = provider

// With MFA and 1-hour session
provider := stscreds.NewAssumeRoleProvider(stsSvc, roleARN)
provider.SerialNumber = aws.String("arn:aws:iam::123456789012:mfa/myuser")
provider.TokenProvider = stscreds.StdinTokenProvider
provider.Duration = time.Hour

Endpoint Credentials

Import: github.com/aws/aws-sdk-go-v2/aws/endpointcreds

Retrieves credentials from an arbitrary HTTP endpoint (used for ECS task credentials).

const ProviderName = "CredentialsEndpointProvider"

type Provider struct {
    aws.SafeCredentialsProvider
    Client       *aws.Client
    ExpiryWindow time.Duration
}

func New(cfg aws.Config) *Provider

Expected JSON response format from endpoint:

{
    "AccessKeyId": "MUA...",
    "SecretAccessKey": "/7PC5om....",
    "Token": "AQoDY....=",        // optional
    "Expiration": "2016-02-25T06:03:31Z"  // optional, omit for static creds
}

Error response format (for HTTP 400/500 responses):

{"code": "ErrorCode", "message": "Helpful error message."}

Plugin Credentials (Linux only, Go 1.8+)

Import: github.com/aws/aws-sdk-go-v2/aws/plugincreds

Load credentials from a Go plugin (.so file).

const ProviderName = "PluginCredentialsProvider"
const ProviderSymbolName = "AWSSDKRetrieveCredentials"

const (
    ErrCodeLookupSymbolError    = "LookupSymbolError"
    ErrCodeInvalidSymbolError   = "InvalidSymbolError"
    ErrCodePluginRetrieveNil    = "PluginRetrieveNilError"
    ErrCodePluginIsExpiredNil   = "PluginIsExpiredNilError"
    ErrCodePluginProviderRetrieve = "PluginProviderRetrieveError"
)

type Provider struct {
    // implements CredentialsProvider
}

func New(p *plugin.Plugin) (*Provider, error)
func GetRetrieveFn(p *plugin.Plugin) (func() (key, secret, token string, exp time.Time, err error), error)
func GetRetrieveFnByName(p *plugin.Plugin, symbolName string) (func() (key, secret, token string, exp time.Time, err error), error)

Plugin must export a symbol AWSSDKRetrieveCredentials with signature:

func() (key, secret, token string, exp time.Time, err error)
import "plugin"

p, err := plugin.Open("credentials.so")
if err != nil { ... }

provider, err := plugincreds.New(p)
if err != nil { ... }
cfg.Credentials = provider

EC2 Metadata Client

Import: github.com/aws/aws-sdk-go-v2/aws/ec2metadata

Client for EC2 Instance Metadata Service. Disable with env var AWS_EC2_METADATA_DISABLED=true.

const ServiceName = "ec2metadata"

type EC2Metadata struct {
    *aws.Client
}

func New(config aws.Config) *EC2Metadata
func (c *EC2Metadata) Available() bool
func (c *EC2Metadata) GetMetadata(p string) (string, error)
func (c *EC2Metadata) GetDynamicData(p string) (string, error)
func (c *EC2Metadata) GetUserData() (string, error)
func (c *EC2Metadata) GetInstanceIdentityDocument() (EC2InstanceIdentityDocument, error)
func (c *EC2Metadata) IAMInfo() (EC2IAMInfo, error)
func (c *EC2Metadata) Region() (string, error)

type EC2IAMInfo struct {
    Code               string
    LastUpdated        time.Time
    InstanceProfileArn string
    InstanceProfileID  string
}

type EC2InstanceIdentityDocument struct {
    DevpayProductCodes []string  `json:"devpayProductCodes"`
    AvailabilityZone   string    `json:"availabilityZone"`
    PrivateIP          string    `json:"privateIp"`
    Version            string    `json:"version"`
    Region             string    `json:"region"`
    InstanceID         string    `json:"instanceId"`
    BillingProducts    []string  `json:"billingProducts"`
    InstanceType       string    `json:"instanceType"`
    AccountID          string    `json:"accountId"`
    PendingTime        time.Time `json:"pendingTime"`
    ImageID            string    `json:"imageId"`
    KernelID           string    `json:"kernelId"`
    RamdiskID          string    `json:"ramdiskId"`
    Architecture       string    `json:"architecture"`
}
meta := ec2metadata.New(cfg)
if meta.Available() {
    region, err := meta.Region()
    doc, err := meta.GetInstanceIdentityDocument()
    iamInfo, err := meta.IAMInfo()
    userData, err := meta.GetUserData()
    // Get any metadata path
    amiID, err := meta.GetMetadata("ami-id")
}

Anonymous Credentials

For unsigned requests (public S3 buckets, etc.):

var AnonymousCredentials = StaticCredentialsProvider{
    Value: Credentials{Source: "AnonymousCredentials"},
}
cfg := baseCfg.Copy()
cfg.Credentials = aws.AnonymousCredentials
svc := s3.New(cfg)
// requests will not be signed

SafeCredentialsProvider (Base Type)

Thread-safe credentials caching. Used as an embedded type by providers.

type SafeCredentialsProvider struct {
    RetrieveFn func() (Credentials, error)
    // unexported fields (mutex, cached value)
}

func (p *SafeCredentialsProvider) Retrieve() (Credentials, error)
func (p *SafeCredentialsProvider) Invalidate()  // force refresh on next Retrieve

NeverExpire Sentinel

var NeverExpire = time.Unix(math.MaxInt64, 0)

Use as Expires when credentials should never expire.

Install with Tessl CLI

npx tessl i tessl/golang-github-com--aws--aws-sdk-go-v2@0.4.0

docs

reference

config.md

core.md

credentials.md

endpoints.md

errors.md

request.md

s3.md

s3manager.md

services.md

signing.md

utilities.md

index.md

tile.json