diff --git a/docs/README.md b/docs/README.md index 5b88d4333bbd..0d265fef6289 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,21 @@ # Documentation -- [Using the AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) -- [AWS Provider contributing guide](https://hashicorp.github.io/terraform-provider-aws/) +This directory contains documentation for the [Terraform AWS Provider Contributor Guide](https://hashicorp.github.io/terraform-provider-aws/). Resource and data source documentation is located in the [`website`](../website/) directory and available in the [Terraform Registry](https://registry.terraform.io/providers/hashicorp/aws/latest/docs). + +## Local Development + +To serve the contributing guide locally, [`mkdocs`](https://www.mkdocs.org/user-guide/installation/) and the [`mkdocs-material`](https://github.com/squidfunk/mkdocs-material#quick-start) extension must be installed. Both require Python and `pip`. + +```console +% pip3 install mkdocs +``` + +```console +% pip3 install mkdocs-material +``` + +Once installed, the documentation can be served from the root directory: + +```console +% mkdocs serve +``` diff --git a/docs/add-a-new-service.md b/docs/add-a-new-service.md index f570c1fa1449..c4d9848c4445 100644 --- a/docs/add-a-new-service.md +++ b/docs/add-a-new-service.md @@ -51,31 +51,63 @@ If an AWS service must be created in a non-standard way, for example the service 1. Add a file `internal//service_package.go` that contains an API client factory function, for example: -```go -package globalaccelerator - -import ( - "context" - - aws_sdkv1 "github.com/aws/aws-sdk-go/aws" - endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints" - session_sdkv1 "github.com/aws/aws-sdk-go/aws/session" - globalaccelerator_sdkv1 "github.com/aws/aws-sdk-go/service/globalaccelerator" -) - -// NewConn returns a new AWS SDK for Go v1 client for this service package's AWS API. -func (p *servicePackage) NewConn(ctx context.Context) (*globalaccelerator_sdkv1.GlobalAccelerator, error) { - sess := p.config["session"].(*session_sdkv1.Session) - config := &aws_sdkv1.Config{Endpoint: aws_sdkv1.String(p.config["endpoint"].(string))} - - // Force "global" services to correct Regions. - if p.config["partition"].(string) == endpoints_sdkv1.AwsPartitionID { - config.Region = aws_sdkv1.String(endpoints_sdkv1.UsWest2RegionID) - } - - return globalaccelerator_sdkv1.New(sess.Copy(config)), nil -} -``` + +=== "aws-go-sdk-v2" + + ```go + package route53domains + + import ( + "context" + + aws_sdkv2 "github.com/aws/aws-sdk-go-v2/aws" + route53domains_sdkv2 "github.com/aws/aws-sdk-go-v2/service/route53domains" + endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints" + ) + + // NewClient returns a new AWS SDK for Go v2 client for this service package's AWS API. + func (p *servicePackage) NewClient(ctx context.Context, config map[string]any) (*route53domains_sdkv2.Client, error) { + cfg := *(config["aws_sdkv2_config"].(*aws_sdkv2.Config)) + + return route53domains_sdkv2.NewFromConfig(cfg, func(o *route53domains_sdkv2.Options) { + if endpoint := config["endpoint"].(string); endpoint != "" { + o.BaseEndpoint = aws_sdkv2.String(endpoint) + } else if config["partition"].(string) == endpoints_sdkv1.AwsPartitionID { + // Route 53 Domains is only available in AWS Commercial us-east-1 Region. + o.Region = endpoints_sdkv1.UsEast1RegionID + } + }), nil + } + ``` + +=== "aws-go-sdk" + + ```go + package globalaccelerator + + import ( + "context" + + aws_sdkv1 "github.com/aws/aws-sdk-go/aws" + endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints" + session_sdkv1 "github.com/aws/aws-sdk-go/aws/session" + globalaccelerator_sdkv1 "github.com/aws/aws-sdk-go/service/globalaccelerator" + ) + + // NewConn returns a new AWS SDK for Go v1 client for this service package's AWS API. + func (p *servicePackage) NewConn(ctx context.Context) (*globalaccelerator_sdkv1.GlobalAccelerator, error) { + sess := p.config["session"].(*session_sdkv1.Session) + config := &aws_sdkv1.Config{Endpoint: aws_sdkv1.String(p.config["endpoint"].(string))} + + // Force "global" services to correct Regions. + if p.config["partition"].(string) == endpoints_sdkv1.AwsPartitionID { + config.Region = aws_sdkv1.String(endpoints_sdkv1.UsWest2RegionID) + } + + return globalaccelerator_sdkv1.New(sess.Copy(config)), nil + } + ``` + ## Customizing a new Service Client @@ -83,30 +115,34 @@ If an AWS service must be customized after creation, for example retry handling 1. Add a file `internal//service_package.go` that contains an API client customization function, for example: -```go -package chime - -import ( - "context" - - aws_sdkv1 "github.com/aws/aws-sdk-go/aws" - request_sdkv1 "github.com/aws/aws-sdk-go/aws/request" - chime_sdkv1 "github.com/aws/aws-sdk-go/service/chime" - "github.com/hashicorp/aws-sdk-go-base/v2/awsv1shim/v2/tfawserr" -) - -// CustomizeConn customizes a new AWS SDK for Go v1 client for this service package's AWS API. -func (p *servicePackage) CustomizeConn(ctx context.Context, conn *chime_sdkv1.Chime) (*chime_sdkv1.Chime, error) { - conn.Handlers.Retry.PushBack(func(r *request_sdkv1.Request) { - // When calling CreateVoiceConnector across multiple resources, - // the API can randomly return a BadRequestException without explanation - if r.Operation.Name == "CreateVoiceConnector" { - if tfawserr.ErrMessageContains(r.Error, chime_sdkv1.ErrCodeBadRequestException, "Service received a bad request") { - r.Retryable = aws_sdkv1.Bool(true) - } - } - }) - - return conn, nil -} -``` + +=== "aws-go-sdk" + + ```go + package chime + + import ( + "context" + + aws_sdkv1 "github.com/aws/aws-sdk-go/aws" + request_sdkv1 "github.com/aws/aws-sdk-go/aws/request" + chime_sdkv1 "github.com/aws/aws-sdk-go/service/chime" + "github.com/hashicorp/aws-sdk-go-base/v2/awsv1shim/v2/tfawserr" + ) + + // CustomizeConn customizes a new AWS SDK for Go v1 client for this service package's AWS API. + func (p *servicePackage) CustomizeConn(ctx context.Context, conn *chime_sdkv1.Chime) (*chime_sdkv1.Chime, error) { + conn.Handlers.Retry.PushBack(func(r *request_sdkv1.Request) { + // When calling CreateVoiceConnector across multiple resources, + // the API can randomly return a BadRequestException without explanation + if r.Operation.Name == "CreateVoiceConnector" { + if tfawserr.ErrMessageContains(r.Error, chime_sdkv1.ErrCodeBadRequestException, "Service received a bad request") { + r.Retryable = aws_sdkv1.Bool(true) + } + } + }) + + return conn, nil + } + ``` + diff --git a/mkdocs.yml b/mkdocs.yml index f88f04a03ae5..1e1577694fbe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,6 +58,7 @@ theme: features: - navigation.instant - content.tabs.link + - content.code.copy plugins: - search: @@ -67,6 +68,8 @@ plugins: markdown_extensions: - pymdownx.highlight - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true - pymdownx.inlinehilite - toc: permalink: "#"