...
AWS SDK for Go API Reference
We announced the upcoming end-of-support for AWS SDK for Go (v1). We recommend that you migrate to AWS SDK for Go v2. For dates, additional details, and information on how to migrate, please refer to the linked announcement.
import "github.com/aws/aws-sdk-go/aws/endpoints"
Overview
Index
Examples

Overview ▾

Package endpoints provides the types and functionality for defining regions and endpoints, as well as querying those definitions.

The SDK's Regions and Endpoints metadata is code generated into the endpoints package, and is accessible via the DefaultResolver function. This function returns a endpoint Resolver will search the metadata and build an associated endpoint if one is found. The default resolver will search all partitions known by the SDK. e.g AWS Standard (aws), AWS China (aws-cn), and AWS GovCloud (US) (aws-us-gov). .

Enumerating Regions and Endpoint Metadata

Casting the Resolver returned by DefaultResolver to a EnumPartitions interface will allow you to get access to the list of underlying Partitions with the Partitions method. This is helpful if you want to limit the SDK's endpoint resolving to a single partition, or enumerate regions, services, and endpoints in the partition.

resolver := endpoints.DefaultResolver()
partitions := resolver.(endpoints.EnumPartitions).Partitions()

for _, p := range partitions {
    fmt.Println("Regions for", p.ID())
    for id, _ := range p.Regions() {
        fmt.Println("*", id)
    }

    fmt.Println("Services for", p.ID())
    for id, _ := range p.Services() {
        fmt.Println("*", id)
    }
}

Using Custom Endpoints

The endpoints package also gives you the ability to use your own logic how endpoints are resolved. This is a great way to define a custom endpoint for select services, without passing that logic down through your code.

If a type implements the Resolver interface it can be used to resolve endpoints. To use this with the SDK's Session and Config set the value of the type to the EndpointsResolver field of aws.Config when initializing the session, or service client.

In addition the ResolverFunc is a wrapper for a func matching the signature of Resolver.EndpointFor, converting it to a type that satisfies the Resolver interface.

myCustomResolver := func(service, region string, optFns ...func(*endpoints.Options)) (endpoints.ResolvedEndpoint, error) {
    if service == endpoints.S3ServiceID {
        return endpoints.ResolvedEndpoint{
            URL:           "s3.custom.endpoint.com",
            SigningRegion: "custom-signing-region",
        }, nil
    }

    return endpoints.DefaultResolver().EndpointFor(service, region, optFns...)
}

sess := session.Must(session.NewSession(&aws.Config{
    Region:           aws.String("us-west-2"),
    EndpointResolver: endpoints.ResolverFunc(myCustomResolver),
}))

Index ▾

Constants
func AddScheme(endpoint string, disableSSL bool) string
func DisableSSLOption(o *Options)
func RegionsForService(ps []Partition, partitionID, serviceID string) (map[string]Region, bool)
func ResolveUnknownServiceOption(o *Options)
func STSRegionalEndpointOption(o *Options)
func StrictMatchingOption(o *Options)
func UseDualStackEndpointOption(o *Options)
func UseDualStackOption(o *Options)
func UseFIPSEndpointOption(o *Options)
type DecodeModelOptions
    func (d *DecodeModelOptions) Set(optFns ...func(*DecodeModelOptions))
type DualStackEndpointState
type EC2IMDSEndpointModeState
    func (e *EC2IMDSEndpointModeState) SetFromString(v string) error
type Endpoint
    func (e Endpoint) ID() string
    func (e Endpoint) ResolveEndpoint(opts ...func(*Options)) (ResolvedEndpoint, error)
    func (e Endpoint) ServiceID() string
type EndpointNotFoundError
type EnumPartitions
type FIPSEndpointState
type Logger
type Options
    func (o *Options) Set(optFns ...func(*Options))
type Partition
    func AwsCnPartition() Partition
    func AwsIsoBPartition() Partition
    func AwsIsoEPartition() Partition
    func AwsIsoFPartition() Partition
    func AwsIsoPartition() Partition
    func AwsPartition() Partition
    func AwsUsGovPartition() Partition
    func DefaultPartitions() []Partition
    func PartitionForRegion(ps []Partition, regionID string) (Partition, bool)
    func (p Partition) DNSSuffix() string
    func (p Partition) EndpointFor(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)
    func (p Partition) ID() string
    func (p Partition) Regions() map[string]Region
    func (p Partition) Services() map[string]Service
type Region
    func (r Region) Description() string
    func (r Region) ID() string
    func (r Region) ResolveEndpoint(service string, opts ...func(*Options)) (ResolvedEndpoint, error)
    func (r Region) Services() map[string]Service
type ResolvedEndpoint
type Resolver
    func DecodeModel(r io.Reader, optFns ...func(*DecodeModelOptions)) (Resolver, error)
    func DefaultResolver() Resolver
type ResolverFunc
    func (fn ResolverFunc) EndpointFor(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)
type S3UsEast1RegionalEndpoint
    func GetS3UsEast1RegionalEndpoint(s string) (S3UsEast1RegionalEndpoint, error)
    func (e S3UsEast1RegionalEndpoint) String() string
type STSRegionalEndpoint
    func GetSTSRegionalEndpoint(s string) (STSRegionalEndpoint, error)
    func (e STSRegionalEndpoint) String() string
type Service
    func (s Service) Endpoints() map[string]Endpoint
    func (s Service) ID() string
    func (s Service) Regions() map[string]Region
    func (s Service) ResolveEndpoint(region string, opts ...func(*Options)) (ResolvedEndpoint, error)
type UnknownEndpointError
    func NewUnknownEndpointError(p, s, r string, known []string) UnknownEndpointError
    func (e UnknownEndpointError) Error() string
    func (e UnknownEndpointError) String() string
type UnknownServiceError
    func NewUnknownServiceError(p, s string, known []string) UnknownServiceError
    func (e UnknownServiceError) Error() string
    func (e UnknownServiceError) String() string

Package files

decode.go defaults.go dep_service_ids.go doc.go endpoints.go legacy_regions.go v3model.go

Constants

const (
    AwsPartitionID      = "aws"        // AWS Standard partition.
    AwsCnPartitionID    = "aws-cn"     // AWS China partition.
    AwsUsGovPartitionID = "aws-us-gov" // AWS GovCloud (US) partition.
    AwsIsoPartitionID   = "aws-iso"    // AWS ISO (US) partition.
    AwsIsoBPartitionID  = "aws-iso-b"  // AWS ISOB (US) partition.
    AwsIsoEPartitionID  = "aws-iso-e"  // AWS ISOE (Europe) partition.
    AwsIsoFPartitionID  = "aws-iso-f"  // AWS ISOF partition.
)

Partition identifiers

const (
    AfSouth1RegionID     = "af-south-1"     // Africa (Cape Town).
    ApEast1RegionID      = "ap-east-1"      // Asia Pacific (Hong Kong).
    ApNortheast1RegionID = "ap-northeast-1" // Asia Pacific (Tokyo).
    ApNortheast2RegionID = "ap-northeast-2" // Asia Pacific (Seoul).
    ApNortheast3RegionID = "ap-northeast-3" // Asia Pacific (Osaka).
    ApSouth1RegionID     = "ap-south-1"     // Asia Pacific (Mumbai).
    ApSouth2RegionID     = "ap-south-2"     // Asia Pacific (Hyderabad).
    ApSoutheast1RegionID = "ap-southeast-1" // Asia Pacific (Singapore).
    ApSoutheast2RegionID = "ap-southeast-2" // Asia Pacific (Sydney).
    ApSoutheast3RegionID = "ap-southeast-3" // Asia Pacific (Jakarta).
    ApSoutheast4RegionID = "ap-southeast-4" // Asia Pacific (Melbourne).
    CaCentral1RegionID   = "ca-central-1"   // Canada (Central).
    CaWest1RegionID      = "ca-west-1"      // Canada West (Calgary).
    EuCentral1RegionID   = "eu-central-1"   // Europe (Frankfurt).
    EuCentral2RegionID   = "eu-central-2"   // Europe (Zurich).
    EuNorth1RegionID     = "eu-north-1"     // Europe (Stockholm).
    EuSouth1RegionID     = "eu-south-1"     // Europe (Milan).
    EuSouth2RegionID     = "eu-south-2"     // Europe (Spain).
    EuWest1RegionID      = "eu-west-1"      // Europe (Ireland).
    EuWest2RegionID      = "eu-west-2"      // Europe (London).
    EuWest3RegionID      = "eu-west-3"      // Europe (Paris).
    IlCentral1RegionID   = "il-central-1"   // Israel (Tel Aviv).
    MeCentral1RegionID   = "me-central-1"   // Middle East (UAE).
    MeSouth1RegionID     = "me-south-1"     // Middle East (Bahrain).
    SaEast1RegionID      = "sa-east-1"      // South America (Sao Paulo).
    UsEast1RegionID      = "us-east-1"      // US East (N. Virginia).
    UsEast2RegionID      = "us-east-2"      // US East (Ohio).
    UsWest1RegionID      = "us-west-1"      // US West (N. California).
    UsWest2RegionID      = "us-west-2"      // US West (Oregon).
)

AWS Standard partition's regions.

const (
    CnNorth1RegionID     = "cn-north-1"     // China (Beijing).
    CnNorthwest1RegionID = "cn-northwest-1" // China (Ningxia).
)

AWS China partition's regions.

const (
    UsGovEast1RegionID = "us-gov-east-1" // AWS GovCloud (US-East).
    UsGovWest1RegionID = "us-gov-west-1" // AWS GovCloud (US-West).
)

AWS GovCloud (US) partition's regions.

const (
    UsIsoEast1RegionID = "us-iso-east-1" // US ISO East.
    UsIsoWest1RegionID = "us-iso-west-1" // US ISO WEST.
)

AWS ISO (US) partition's regions.

const (
    A4bServiceID                          = "a4b"                          // A4b.
    AcmServiceID                          = "acm"                          // Acm.
    AcmPcaServiceID                       = "acm-pca"                      // AcmPca.
    ApiMediatailorServiceID               = "api.mediatailor"              // ApiMediatailor.
    ApiPricingServiceID                   = "api.pricing"                  // ApiPricing.
    ApiSagemakerServiceID                 = "api.sagemaker"                // ApiSagemaker.
    ApigatewayServiceID                   = "apigateway"                   // Apigateway.
    ApplicationAutoscalingServiceID       = "application-autoscaling"      // ApplicationAutoscaling.
    Appstream2ServiceID                   = "appstream2"                   // Appstream2.
    AppsyncServiceID                      = "appsync"                      // Appsync.
    AthenaServiceID                       = "athena"                       // Athena.
    AutoscalingServiceID                  = "autoscaling"                  // Autoscaling.
    AutoscalingPlansServiceID             = "autoscaling-plans"            // AutoscalingPlans.
    BatchServiceID                        = "batch"                        // Batch.
    BudgetsServiceID                      = "budgets"                      // Budgets.
    CeServiceID                           = "ce"                           // Ce.
    ChimeServiceID                        = "chime"                        // Chime.
    Cloud9ServiceID                       = "cloud9"                       // Cloud9.
    ClouddirectoryServiceID               = "clouddirectory"               // Clouddirectory.
    CloudformationServiceID               = "cloudformation"               // Cloudformation.
    CloudfrontServiceID                   = "cloudfront"                   // Cloudfront.
    CloudhsmServiceID                     = "cloudhsm"                     // Cloudhsm.
    Cloudhsmv2ServiceID                   = "cloudhsmv2"                   // Cloudhsmv2.
    CloudsearchServiceID                  = "cloudsearch"                  // Cloudsearch.
    CloudtrailServiceID                   = "cloudtrail"                   // Cloudtrail.
    CodebuildServiceID                    = "codebuild"                    // Codebuild.
    CodecommitServiceID                   = "codecommit"                   // Codecommit.
    CodedeployServiceID                   = "codedeploy"                   // Codedeploy.
    CodepipelineServiceID                 = "codepipeline"                 // Codepipeline.
    CodestarServiceID                     = "codestar"                     // Codestar.
    CognitoIdentityServiceID              = "cognito-identity"             // CognitoIdentity.
    CognitoIdpServiceID                   = "cognito-idp"                  // CognitoIdp.
    CognitoSyncServiceID                  = "cognito-sync"                 // CognitoSync.
    ComprehendServiceID                   = "comprehend"                   // Comprehend.
    ConfigServiceID                       = "config"                       // Config.
    CurServiceID                          = "cur"                          // Cur.
    DatapipelineServiceID                 = "datapipeline"                 // Datapipeline.
    DaxServiceID                          = "dax"                          // Dax.
    DevicefarmServiceID                   = "devicefarm"                   // Devicefarm.
    DirectconnectServiceID                = "directconnect"                // Directconnect.
    DiscoveryServiceID                    = "discovery"                    // Discovery.
    DmsServiceID                          = "dms"                          // Dms.
    DsServiceID                           = "ds"                           // Ds.
    DynamodbServiceID                     = "dynamodb"                     // Dynamodb.
    Ec2ServiceID                          = "ec2"                          // Ec2.
    Ec2metadataServiceID                  = "ec2metadata"                  // Ec2metadata.
    EcrServiceID                          = "ecr"                          // Ecr.
    EcsServiceID                          = "ecs"                          // Ecs.
    ElasticacheServiceID                  = "elasticache"                  // Elasticache.
    ElasticbeanstalkServiceID             = "elasticbeanstalk"             // Elasticbeanstalk.
    ElasticfilesystemServiceID            = "elasticfilesystem"            // Elasticfilesystem.
    ElasticloadbalancingServiceID         = "elasticloadbalancing"         // Elasticloadbalancing.
    ElasticmapreduceServiceID             = "elasticmapreduce"             // Elasticmapreduce.
    ElastictranscoderServiceID            = "elastictranscoder"            // Elastictranscoder.
    EmailServiceID                        = "email"                        // Email.
    EntitlementMarketplaceServiceID       = "entitlement.marketplace"      // EntitlementMarketplace.
    EsServiceID                           = "es"                           // Es.
    EventsServiceID                       = "events"                       // Events.
    FirehoseServiceID                     = "firehose"                     // Firehose.
    FmsServiceID                          = "fms"                          // Fms.
    GameliftServiceID                     = "gamelift"                     // Gamelift.
    GlacierServiceID                      = "glacier"                      // Glacier.
    GlueServiceID                         = "glue"                         // Glue.
    GreengrassServiceID                   = "greengrass"                   // Greengrass.
    GuarddutyServiceID                    = "guardduty"                    // Guardduty.
    HealthServiceID                       = "health"                       // Health.
    IamServiceID                          = "iam"                          // Iam.
    ImportexportServiceID                 = "importexport"                 // Importexport.
    InspectorServiceID                    = "inspector"                    // Inspector.
    IotServiceID                          = "iot"                          // Iot.
    IotanalyticsServiceID                 = "iotanalytics"                 // Iotanalytics.
    KinesisServiceID                      = "kinesis"                      // Kinesis.
    KinesisanalyticsServiceID             = "kinesisanalytics"             // Kinesisanalytics.
    KinesisvideoServiceID                 = "kinesisvideo"                 // Kinesisvideo.
    KmsServiceID                          = "kms"                          // Kms.
    LambdaServiceID                       = "lambda"                       // Lambda.
    LightsailServiceID                    = "lightsail"                    // Lightsail.
    LogsServiceID                         = "logs"                         // Logs.
    MachinelearningServiceID              = "machinelearning"              // Machinelearning.
    MarketplacecommerceanalyticsServiceID = "marketplacecommerceanalytics" // Marketplacecommerceanalytics.
    MediaconvertServiceID                 = "mediaconvert"                 // Mediaconvert.
    MedialiveServiceID                    = "medialive"                    // Medialive.
    MediapackageServiceID                 = "mediapackage"                 // Mediapackage.
    MediastoreServiceID                   = "mediastore"                   // Mediastore.
    MeteringMarketplaceServiceID          = "metering.marketplace"         // MeteringMarketplace.
    MghServiceID                          = "mgh"                          // Mgh.
    MobileanalyticsServiceID              = "mobileanalytics"              // Mobileanalytics.
    ModelsLexServiceID                    = "models.lex"                   // ModelsLex.
    MonitoringServiceID                   = "monitoring"                   // Monitoring.
    MturkRequesterServiceID               = "mturk-requester"              // MturkRequester.
    NeptuneServiceID                      = "neptune"                      // Neptune.
    OpsworksServiceID                     = "opsworks"                     // Opsworks.
    OpsworksCmServiceID                   = "opsworks-cm"                  // OpsworksCm.
    OrganizationsServiceID                = "organizations"                // Organizations.
    PinpointServiceID                     = "pinpoint"                     // Pinpoint.
    PollyServiceID                        = "polly"                        // Polly.
    RdsServiceID                          = "rds"                          // Rds.
    RedshiftServiceID                     = "redshift"                     // Redshift.
    RekognitionServiceID                  = "rekognition"                  // Rekognition.
    ResourceGroupsServiceID               = "resource-groups"              // ResourceGroups.
    Route53ServiceID                      = "route53"                      // Route53.
    Route53domainsServiceID               = "route53domains"               // Route53domains.
    RuntimeLexServiceID                   = "runtime.lex"                  // RuntimeLex.
    RuntimeSagemakerServiceID             = "runtime.sagemaker"            // RuntimeSagemaker.
    S3ServiceID                           = "s3"                           // S3.
    S3ControlServiceID                    = "s3-control"                   // S3Control.
    SagemakerServiceID                    = "api.sagemaker"                // Sagemaker.
    SdbServiceID                          = "sdb"                          // Sdb.
    SecretsmanagerServiceID               = "secretsmanager"               // Secretsmanager.
    ServerlessrepoServiceID               = "serverlessrepo"               // Serverlessrepo.
    ServicecatalogServiceID               = "servicecatalog"               // Servicecatalog.
    ServicediscoveryServiceID             = "servicediscovery"             // Servicediscovery.
    ShieldServiceID                       = "shield"                       // Shield.
    SmsServiceID                          = "sms"                          // Sms.
    SnowballServiceID                     = "snowball"                     // Snowball.
    SnsServiceID                          = "sns"                          // Sns.
    SqsServiceID                          = "sqs"                          // Sqs.
    SsmServiceID                          = "ssm"                          // Ssm.
    StatesServiceID                       = "states"                       // States.
    StoragegatewayServiceID               = "storagegateway"               // Storagegateway.
    StreamsDynamodbServiceID              = "streams.dynamodb"             // StreamsDynamodb.
    StsServiceID                          = "sts"                          // Sts.
    SupportServiceID                      = "support"                      // Support.
    SwfServiceID                          = "swf"                          // Swf.
    TaggingServiceID                      = "tagging"                      // Tagging.
    TransferServiceID                     = "transfer"                     // Transfer.
    TranslateServiceID                    = "translate"                    // Translate.
    WafServiceID                          = "waf"                          // Waf.
    WafRegionalServiceID                  = "waf-regional"                 // WafRegional.
    WorkdocsServiceID                     = "workdocs"                     // Workdocs.
    WorkmailServiceID                     = "workmail"                     // Workmail.
    WorkspacesServiceID                   = "workspaces"                   // Workspaces.
    XrayServiceID                         = "xray"                         // Xray.
)

Service identifiers

Deprecated: Use client package's EndpointsID value instead of these ServiceIDs. These IDs are not maintained, and are out of date.

const (
    UsIsobEast1RegionID = "us-isob-east-1" // US ISOB East (Ohio).
)

AWS ISOB (US) partition's regions.

func AddScheme

func AddScheme(endpoint string, disableSSL bool) string

AddScheme adds the HTTP or HTTPS schemes to a endpoint URL if there is no scheme. If disableSSL is true HTTP will set HTTP instead of the default HTTPS.

If disableSSL is set, it will only set the URL's scheme if the URL does not contain a scheme.

func DisableSSLOption

func DisableSSLOption(o *Options)

DisableSSLOption sets the DisableSSL options. Can be used as a functional option when resolving endpoints.

func RegionsForService

func RegionsForService(ps []Partition, partitionID, serviceID string) (map[string]Region, bool)

RegionsForService returns a map of regions for the partition and service. If either the partition or service does not exist false will be returned as the second parameter.

This example shows how to get the regions for DynamoDB in the AWS partition.

rs, exists := endpoints.RegionsForService(endpoints.DefaultPartitions(), endpoints.AwsPartitionID, endpoints.DynamodbServiceID)

This is equivalent to using the partition directly.

rs := endpoints.AwsPartition().Services()[endpoints.DynamodbServiceID].Regions()

func ResolveUnknownServiceOption

func ResolveUnknownServiceOption(o *Options)

ResolveUnknownServiceOption sets the ResolveUnknownService option. Can be used as a functional option when resolving endpoints.

func STSRegionalEndpointOption

func STSRegionalEndpointOption(o *Options)

STSRegionalEndpointOption enables the STS endpoint resolver behavior to resolve STS endpoint to their regional endpoint, instead of the global endpoint.

func StrictMatchingOption

func StrictMatchingOption(o *Options)

StrictMatchingOption sets the StrictMatching option. Can be used as a functional option when resolving endpoints.

func UseDualStackEndpointOption

func UseDualStackEndpointOption(o *Options)

UseDualStackEndpointOption sets the UseDualStackEndpoint option to enabled. Can be used as a functional option when resolving endpoints.

func UseDualStackOption

func UseDualStackOption(o *Options)

UseDualStackOption sets the UseDualStack option. Can be used as a functional option when resolving endpoints.

Deprecated: UseDualStackEndpointOption should be used to enable usage of a service's dual-stack endpoint. When DualStackEndpointState is set to a non-zero value it takes higher precedence then this option.

func UseFIPSEndpointOption

func UseFIPSEndpointOption(o *Options)

UseFIPSEndpointOption sets the UseFIPSEndpoint option to enabled. Can be used as a functional option when resolving endpoints.

type DecodeModelOptions

type DecodeModelOptions struct {
    SkipCustomizations bool
}

A DecodeModelOptions are the options for how the endpoints model definition are decoded.

func (*DecodeModelOptions) Set

func (d *DecodeModelOptions) Set(optFns ...func(*DecodeModelOptions))

Set combines all of the option functions together.

type DualStackEndpointState

type DualStackEndpointState uint

DualStackEndpointState is a constant to describe the dual-stack endpoint resolution behavior.

const (
    // DualStackEndpointStateUnset is the default value behavior for dual-stack endpoint
    // resolution.
    DualStackEndpointStateUnset DualStackEndpointState = iota

    // DualStackEndpointStateEnabled enable dual-stack endpoint resolution for endpoints.
    DualStackEndpointStateEnabled

    // DualStackEndpointStateDisabled disables dual-stack endpoint resolution for endpoints.
    DualStackEndpointStateDisabled
)

type EC2IMDSEndpointModeState

type EC2IMDSEndpointModeState uint

EC2IMDSEndpointModeState is an enum configuration variable describing the client endpoint mode.

const (
    EC2IMDSEndpointModeStateUnset EC2IMDSEndpointModeState = iota
    EC2IMDSEndpointModeStateIPv4
    EC2IMDSEndpointModeStateIPv6
)

Enumeration values for EC2IMDSEndpointModeState

func (*EC2IMDSEndpointModeState) SetFromString

func (e *EC2IMDSEndpointModeState) SetFromString(v string) error

SetFromString sets the EC2IMDSEndpointModeState based on the provided string value. Unknown values will default to EC2IMDSEndpointModeStateUnset

type Endpoint

type Endpoint struct {
    // contains filtered or unexported fields
}

A Endpoint provides information about endpoints, and provides the ability to resolve that endpoint for the service, and the region the endpoint represents.

func (Endpoint) ID

func (e Endpoint) ID() string

ID returns the identifier for an endpoint.

func (Endpoint) ResolveEndpoint

func (e Endpoint) ResolveEndpoint(opts ...func(*Options)) (ResolvedEndpoint, error)

ResolveEndpoint resolves an endpoint from the context of a service and region the endpoint represents. See Partition.EndpointFor for usage and errors that can be returned.

func (Endpoint) ServiceID

func (e Endpoint) ServiceID() string

ServiceID returns the identifier the endpoint belongs to.

type EndpointNotFoundError

type EndpointNotFoundError struct {
    Partition string
    Service   string
    Region    string
    // contains filtered or unexported fields
}

A EndpointNotFoundError is returned when in StrictMatching mode, and the endpoint for the service and region cannot be found in any of the partitions.

type EnumPartitions

type EnumPartitions interface {
    Partitions() []Partition
}

EnumPartitions a provides a way to retrieve the underlying partitions that make up the SDK's default Resolver, or any resolver decoded from a model file.

Use this interface with DefaultResolver and DecodeModels to get the list of Partitions.

Example

Code:

resolver := endpoints.DefaultResolver()
partitions := resolver.(endpoints.EnumPartitions).Partitions()

for _, p := range partitions {
    fmt.Println("Regions for", p.ID())
    for id := range p.Regions() {
        fmt.Println("*", id)
    }

    fmt.Println("Services for", p.ID())
    for id := range p.Services() {
        fmt.Println("*", id)
    }
}

type FIPSEndpointState

type FIPSEndpointState uint

FIPSEndpointState is a constant to describe the FIPS endpoint resolution behavior.

const (
    // FIPSEndpointStateUnset is the default value behavior for FIPS endpoint resolution.
    FIPSEndpointStateUnset FIPSEndpointState = iota

    // FIPSEndpointStateEnabled enables FIPS endpoint resolution for service endpoints.
    FIPSEndpointStateEnabled

    // FIPSEndpointStateDisabled disables FIPS endpoint resolution for endpoints.
    FIPSEndpointStateDisabled
)

type Logger

type Logger interface {
    Log(...interface{})
}

A Logger is a minimalistic interface for the SDK to log messages to.

type Options

type Options struct {
    // DisableSSL forces the endpoint to be resolved as HTTP.
    // instead of HTTPS if the service supports it.
    DisableSSL bool

    // Sets the resolver to resolve the endpoint as a dualstack endpoint
    // for the service. If dualstack support for a service is not known and
    // StrictMatching is not enabled a dualstack endpoint for the service will
    // be returned. This endpoint may not be valid. If StrictMatching is
    // enabled only services that are known to support dualstack will return
    // dualstack endpoints.
    //
    // Deprecated: This option will continue to function for S3 and S3 Control for backwards compatibility.
    // UseDualStackEndpoint should be used to enable usage of a service's dual-stack endpoint for all service clients
    // moving forward. For S3 and S3 Control, when UseDualStackEndpoint is set to a non-zero value it takes higher
    // precedence then this option.
    UseDualStack bool

    // Sets the resolver to resolve a dual-stack endpoint for the service.
    UseDualStackEndpoint DualStackEndpointState

    // UseFIPSEndpoint specifies the resolver must resolve a FIPS endpoint.
    UseFIPSEndpoint FIPSEndpointState

    // Enables strict matching of services and regions resolved endpoints.
    // If the partition doesn't enumerate the exact service and region an
    // error will be returned. This option will prevent returning endpoints
    // that look valid, but may not resolve to any real endpoint.
    StrictMatching bool

    // Enables resolving a service endpoint based on the region provided if the
    // service does not exist. The service endpoint ID will be used as the service
    // domain name prefix. By default the endpoint resolver requires the service
    // to be known when resolving endpoints.
    //
    // If resolving an endpoint on the partition list the provided region will
    // be used to determine which partition's domain name pattern to the service
    // endpoint ID with. If both the service and region are unknown and resolving
    // the endpoint on partition list an UnknownEndpointError error will be returned.
    //
    // If resolving and endpoint on a partition specific resolver that partition's
    // domain name pattern will be used with the service endpoint ID. If both
    // region and service do not exist when resolving an endpoint on a specific
    // partition the partition's domain pattern will be used to combine the
    // endpoint and region together.
    //
    // This option is ignored if StrictMatching is enabled.
    ResolveUnknownService bool

    // Specifies the EC2 Instance Metadata Service default endpoint selection mode (IPv4 or IPv6)
    EC2MetadataEndpointMode EC2IMDSEndpointModeState

    // STS Regional Endpoint flag helps with resolving the STS endpoint
    STSRegionalEndpoint STSRegionalEndpoint

    // S3 Regional Endpoint flag helps with resolving the S3 endpoint
    S3UsEast1RegionalEndpoint S3UsEast1RegionalEndpoint

    // ResolvedRegion is the resolved region string. If provided (non-zero length) it takes priority
    // over the region name passed to the ResolveEndpoint call.
    ResolvedRegion string

    // Logger is the logger that will be used to log messages.
    Logger Logger

    // Determines whether logging of deprecated endpoints usage is enabled.
    LogDeprecated bool
}

Options provide the configuration needed to direct how the endpoints will be resolved.

func (*Options) Set

func (o *Options) Set(optFns ...func(*Options))

Set combines all of the option functions together.

type Partition

type Partition struct {
    // contains filtered or unexported fields
}

A Partition provides the ability to enumerate the partition's regions and services.

func AwsCnPartition

func AwsCnPartition() Partition

AwsCnPartition returns the Resolver for AWS China.

func AwsIsoBPartition

func AwsIsoBPartition() Partition

AwsIsoBPartition returns the Resolver for AWS ISOB (US).

func AwsIsoEPartition

func AwsIsoEPartition() Partition

AwsIsoEPartition returns the Resolver for AWS ISOE (Europe).

func AwsIsoFPartition

func AwsIsoFPartition() Partition

AwsIsoFPartition returns the Resolver for AWS ISOF.

func AwsIsoPartition

func AwsIsoPartition() Partition

AwsIsoPartition returns the Resolver for AWS ISO (US).

func AwsPartition

func AwsPartition() Partition

AwsPartition returns the Resolver for AWS Standard.

func AwsUsGovPartition

func AwsUsGovPartition() Partition

AwsUsGovPartition returns the Resolver for AWS GovCloud (US).

func DefaultPartitions

func DefaultPartitions() []Partition

DefaultPartitions returns a list of the partitions the SDK is bundled with. The available partitions are: AWS Standard, AWS China, AWS GovCloud (US), AWS ISO (US), AWS ISOB (US), AWS ISOE (Europe), and AWS ISOF.

partitions := endpoints.DefaultPartitions
for _, p := range partitions {
    // ... inspect partitions
}

func PartitionForRegion

func PartitionForRegion(ps []Partition, regionID string) (Partition, bool)

PartitionForRegion returns the first partition which includes the region passed in. This includes both known regions and regions which match a pattern supported by the partition which may include regions that are not explicitly known by the partition. Use the Regions method of the returned Partition if explicit support is needed.

func (Partition) DNSSuffix

func (p Partition) DNSSuffix() string

DNSSuffix returns the base domain name of the partition.

func (Partition) EndpointFor

func (p Partition) EndpointFor(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)

EndpointFor attempts to resolve the endpoint based on service and region. See Options for information on configuring how the endpoint is resolved.

If the service cannot be found in the metadata the UnknownServiceError error will be returned. This validation will occur regardless if StrictMatching is enabled. To enable resolving unknown services set the "ResolveUnknownService" option to true. When StrictMatching is disabled this option allows the partition resolver to resolve a endpoint based on the service endpoint ID provided.

When resolving endpoints you can choose to enable StrictMatching. This will require the provided service and region to be known by the partition. If the endpoint cannot be strictly resolved an error will be returned. This mode is useful to ensure the endpoint resolved is valid. Without StrictMatching enabled the endpoint returned may look valid but may not work. StrictMatching requires the SDK to be updated if you want to take advantage of new regions and services expansions.

Errors that can be returned.

  • UnknownServiceError
  • UnknownEndpointError

func (Partition) ID

func (p Partition) ID() string

ID returns the identifier of the partition.

func (Partition) Regions

func (p Partition) Regions() map[string]Region

Regions returns a map of Regions indexed by their ID. This is useful for enumerating over the regions in a partition.

func (Partition) Services

func (p Partition) Services() map[string]Service

Services returns a map of Service indexed by their ID. This is useful for enumerating over the services in a partition.

type Region

type Region struct {
    // contains filtered or unexported fields
}

A Region provides information about a region, and ability to resolve an endpoint from the context of a region, given a service.

func (Region) Description

func (r Region) Description() string

Description returns the region's description. The region description is free text, it can be empty, and it may change between SDK releases.

func (Region) ID

func (r Region) ID() string

ID returns the region's identifier.

func (Region) ResolveEndpoint

func (r Region) ResolveEndpoint(service string, opts ...func(*Options)) (ResolvedEndpoint, error)

ResolveEndpoint resolves an endpoint from the context of the region given a service. See Partition.EndpointFor for usage and errors that can be returned.

func (Region) Services

func (r Region) Services() map[string]Service

Services returns a list of all services that are known to be in this region.

type ResolvedEndpoint

type ResolvedEndpoint struct {
    // The endpoint URL
    URL string

    // The endpoint partition
    PartitionID string

    // The region that should be used for signing requests.
    SigningRegion string

    // The service name that should be used for signing requests.
    SigningName string

    // States that the signing name for this endpoint was derived from metadata
    // passed in, but was not explicitly modeled.
    SigningNameDerived bool

    // The signing method that should be used for signing requests.
    SigningMethod string
}

A ResolvedEndpoint is an endpoint that has been resolved based on a partition service, and region.

type Resolver

type Resolver interface {
    EndpointFor(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)
}

A Resolver provides the interface for functionality to resolve endpoints. The build in Partition and DefaultResolver return value satisfy this interface.

func DecodeModel

func DecodeModel(r io.Reader, optFns ...func(*DecodeModelOptions)) (Resolver, error)

DecodeModel unmarshals a Regions and Endpoint model definition file into a endpoint Resolver. If the file format is not supported, or an error occurs when unmarshaling the model an error will be returned.

Casting the return value of this func to a EnumPartitions will allow you to get a list of the partitions in the order the endpoints will be resolved in.

resolver, err := endpoints.DecodeModel(reader)

partitions := resolver.(endpoints.EnumPartitions).Partitions()
for _, p := range partitions {
    // ... inspect partitions
}

func DefaultResolver

func DefaultResolver() Resolver

DefaultResolver returns an Endpoint resolver that will be able to resolve endpoints for: AWS Standard, AWS China, AWS GovCloud (US), AWS ISO (US), AWS ISOB (US), AWS ISOE (Europe), and AWS ISOF.

Use DefaultPartitions() to get the list of the default partitions.

type ResolverFunc

type ResolverFunc func(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)

ResolverFunc is a helper utility that wraps a function so it satisfies the Resolver interface. This is useful when you want to add additional endpoint resolving logic, or stub out specific endpoints with custom values.

Example

Code:

myCustomResolver := func(service, region string, optFns ...func(*endpoints.Options)) (
    endpoints.ResolvedEndpoint, error,
) {
    if service == endpoints.S3ServiceID {
        return endpoints.ResolvedEndpoint{
            URL:           "s3.custom.endpoint.com",
            SigningRegion: "custom-signing-region",
        }, nil
    }

    return endpoints.DefaultResolver().EndpointFor(service, region, optFns...)
}

sess := session.Must(session.NewSession(&aws.Config{
    Region:           aws.String("us-west-2"),
    EndpointResolver: endpoints.ResolverFunc(myCustomResolver),
}))

// Create the S3 service client with the shared session. This will
// automatically use the S3 custom endpoint configured in the custom
// endpoint resolver wrapping the default endpoint resolver.
s3Svc := s3.New(sess)
// Operation calls will be made to the custom endpoint.
s3Svc.GetObject(&s3.GetObjectInput{
    Bucket: aws.String("myBucket"),
    Key:    aws.String("myObjectKey"),
})

// Create the SQS service client with the shared session. This will
// fallback to the default endpoint resolver because the customization
// passes any non S3 service endpoint resolve to the default resolver.
sqsSvc := sqs.New(sess)
// Operation calls will be made to the default endpoint for SQS for the
// region configured.
sqsSvc.ReceiveMessage(&sqs.ReceiveMessageInput{
    QueueUrl: aws.String("my-queue-url"),
})

func (ResolverFunc) EndpointFor

func (fn ResolverFunc) EndpointFor(service, region string, opts ...func(*Options)) (ResolvedEndpoint, error)

EndpointFor wraps the ResolverFunc function to satisfy the Resolver interface.

type S3UsEast1RegionalEndpoint

type S3UsEast1RegionalEndpoint int

S3UsEast1RegionalEndpoint is an enum for the states of the S3 us-east-1 Regional Endpoint options.

const (

    // UnsetS3UsEast1Endpoint represents that S3 Regional Endpoint flag is not
    // specified.
    UnsetS3UsEast1Endpoint S3UsEast1RegionalEndpoint = iota

    // LegacyS3UsEast1Endpoint represents when S3 Regional Endpoint flag is
    // specified to use legacy endpoints.
    LegacyS3UsEast1Endpoint

    // RegionalS3UsEast1Endpoint represents when S3 Regional Endpoint flag is
    // specified to use regional endpoints.
    RegionalS3UsEast1Endpoint
)

func GetS3UsEast1RegionalEndpoint

func GetS3UsEast1RegionalEndpoint(s string) (S3UsEast1RegionalEndpoint, error)

GetS3UsEast1RegionalEndpoint function returns the S3UsEast1RegionalEndpointFlag based on the input string provided in env config or shared config by the user.

`legacy`, `regional` are the only case-insensitive valid strings for resolving the S3 regional Endpoint flag.

func (S3UsEast1RegionalEndpoint) String

func (e S3UsEast1RegionalEndpoint) String() string

type STSRegionalEndpoint

type STSRegionalEndpoint int

STSRegionalEndpoint is an enum for the states of the STS Regional Endpoint options.

const (

    // UnsetSTSEndpoint represents that STS Regional Endpoint flag is not specified.
    UnsetSTSEndpoint STSRegionalEndpoint = iota

    // LegacySTSEndpoint represents when STS Regional Endpoint flag is specified
    // to use legacy endpoints.
    LegacySTSEndpoint

    // RegionalSTSEndpoint represents when STS Regional Endpoint flag is specified
    // to use regional endpoints.
    RegionalSTSEndpoint
)

func GetSTSRegionalEndpoint

func GetSTSRegionalEndpoint(s string) (STSRegionalEndpoint, error)

GetSTSRegionalEndpoint function returns the STSRegionalEndpointFlag based on the input string provided in env config or shared config by the user.

`legacy`, `regional` are the only case-insensitive valid strings for resolving the STS regional Endpoint flag.

func (STSRegionalEndpoint) String

func (e STSRegionalEndpoint) String() string

type Service

type Service struct {
    // contains filtered or unexported fields
}

A Service provides information about a service, and ability to resolve an endpoint from the context of a service, given a region.

func (Service) Endpoints

func (s Service) Endpoints() map[string]Endpoint

Endpoints returns a map of Endpoints indexed by their ID for all known endpoints for a service.

A region is the AWS region the service exists in. Whereas a Endpoint is an URL that can be resolved to a instance of a service.

func (Service) ID

func (s Service) ID() string

ID returns the identifier for the service.

func (Service) Regions

func (s Service) Regions() map[string]Region

Regions returns a map of Regions that the service is present in.

A region is the AWS region the service exists in. Whereas a Endpoint is an URL that can be resolved to a instance of a service.

func (Service) ResolveEndpoint

func (s Service) ResolveEndpoint(region string, opts ...func(*Options)) (ResolvedEndpoint, error)

ResolveEndpoint resolves an endpoint from the context of a service given a region. See Partition.EndpointFor for usage and errors that can be returned.

type UnknownEndpointError

type UnknownEndpointError struct {
    Partition string
    Service   string
    Region    string
    Known     []string
    // contains filtered or unexported fields
}

A UnknownEndpointError is returned when in StrictMatching mode and the service is valid, but the region does not resolve to an endpoint. Includes a list of all known endpoints for the service.

func NewUnknownEndpointError

func NewUnknownEndpointError(p, s, r string, known []string) UnknownEndpointError

NewUnknownEndpointError builds and returns UnknownEndpointError.

func (UnknownEndpointError) Error

func (e UnknownEndpointError) Error() string

String returns the string representation of the error.

func (UnknownEndpointError) String

func (e UnknownEndpointError) String() string

String returns the string representation of the error.

type UnknownServiceError

type UnknownServiceError struct {
    Partition string
    Service   string
    Known     []string
    // contains filtered or unexported fields
}

A UnknownServiceError is returned when the service does not resolve to an endpoint. Includes a list of all known services for the partition. Returned when a partition does not support the service.

func NewUnknownServiceError

func NewUnknownServiceError(p, s string, known []string) UnknownServiceError

NewUnknownServiceError builds and returns UnknownServiceError.

func (UnknownServiceError) Error

func (e UnknownServiceError) Error() string

String returns the string representation of the error.

func (UnknownServiceError) String

func (e UnknownServiceError) String() string

String returns the string representation of the error.