Skip to content

Latest commit

 

History

History
 
 

names

README.md

names

Package names provides AWS service-name information that is critical to the Terraform AWS Provider working correctly. If you are unsure about a change you are making, please do not hesitate to ask!

NOTE: The information in data/names_data.hcl affects the provider, generators, documentation, website navigation, etc. working correctly. Please do not make any changes until you understand the table below.

The core of the names package is data/names_data.hcl, which contains HCL data about naming in the AWS Provider, AWS Go SDKs v1 and v2, and AWS CLI. The file is dynamically embedded at build time in the AWS Provider and referenced by generators when generating code. The information it contains must be correct. Please double-check any changes.

Consumers of names include:

  • Package provider (internal/provider)
  • Package conns (internal/conns)
  • AWS Provider generators
  • skaff tool

After any edits to data/names_data.hcl, run make gen. Doing so regenerates code and performs checks on data/names_data.hcl.

The schema of the attributes and blocks of data/names_data.hcl are as follows:

service "" {

  // If both of these attributes are the same as the service block's name, this block will be ommitted
  cli_v2_command { 
    aws_cli_v2_command           = ""
    aws_cli_v2_command_no_dashes = ""
  }

  // If both of these attributes are the same as the service block's name, this block will be ommitted
  go_packages { 
    v1_package = ""
    v2_package = ""
  } 

  // If any blocks below here have attirbutes with empty strings or false bools, they will be ommitted
  // Blocks with zero attributes will be ommitted 
  sdk {
    id             = "" 
    client_version = 2 
  }

  names {
    aliases             = [""] // This can also be excluded if it is empty
    provider_name_upper = ""
    human_friendly      = ""
  }

  client {
    go_v1_client_typename = ""
    skip_client_generate  = bool
  }

  env_var {
    deprecated_env_var = ""
    tf_aws_env_var     = ""
  }

  endpoint_info {
    endpoint_api_call        = ""
    endpoint_api_params      = ""
    endpoint_region_override = ""
    endpoint_only            = bool
  }

  resource_prefix {
    actual  = ""
    correct = ""
  }

  provider_package_correct = ""
  split_package       = ""
  file_prefix         = ""
  doc_prefix          = [""]
  brand               = ""
  exclude             = bool
  not_implemented     = bool
  allowed_subcategory = bool
  note                = ""
}

The explanation of the attributes of data/names_data.hcl are as follows:

Name Use Description
ProviderPackageActual Code Actual TF AWS provide package name if provider_package_correct is not used; takes precedence over provider_package_correct for service block name if both are defined
aws_cli_v2_command Reference Service command in AWS CLI v2
aws_cli_v2_command_no_dashes Reference Same as aws_cli_v2_command without dashes
v1_package Code AWS SDK for Go v1 package name
v2_package Code AWS SDK for Go v2 package name
id Code Represents the ServiceID of a AWS service which is a unique identifier of a specific service
client_version Code Indicates which version of the AWS SDK is used for this service. Defaults to 2
aliases Code HCL string list of name variations (e.g., for "AMP", prometheus,prometheusservice). Do not include **ProviderPackageActual (or provider_package_correct, if blank) since that will create duplicates in the Custom Endpoints guide.
provider_name_upper Code Correctly capitalized ProviderPackageActual, if it exists, otherwise provider_package_correct
human_friendly Code [REQUIRED] Human-friendly name of service as used by AWS; documentation subcategory must exactly match this value; used in website navigation and error messages
go_v1_client_typename Code Exact name (i.e., spelling and capitalization) of the AWS SDK for Go v1 client type (e.g., see the New() return type for SES). Also excluded when service only supports AWS SDK for Go v2
skip_client_generate Code Some service clients need special configuration rather than the default generated configuration; use a non-empty value to skip generation but you must then manually configure the client in internal/conns/config.go
deprecated_env_var Code Deprecated AWS_<service>_ENDPOINT envvar defined for some services
tf_aws_env_var Code TF_AWS_<service>_ENDPOINT envvar defined for some services
endpoint_api_call Code Command for the AWS cli for describing the current service
endpoint_api_params Code Used in service_endpoints_gen_test.go files for API calls that require a configured value
endpoint_region_override Code Specified alternate regional endpoint for API requests
endpoint_only Code Bool based on if not_implemented is non-blank, whether the service endpoint should be included in the provider endpoints configuration
resource_prefix_actual Code Regular expression to match anomalous TF resource name prefixes (e.g., for the resource name aws_config_config_rule, aws_config_ will match all resources); only use if resource_prefix_correct is not suitable (e.g., aws_codepipeline_ won't work as there is only one resource named aws_codepipeline); takes precedence over resource_prefix_correct
resource_prefix_correct Code Regular expression to match what resource name prefixes should be (i.e., aws_ + provider_package_correct + _); used if resource_prefix_actual is blank
provider_package_correct Code Shorter of aws_cli_v2_command_no_dashes and v2_package; should not be blank if either exists; same as Service Identifier; what the TF AWS Provider package name should be; ProviderPackageActual takes precedence
split_package_real_package Code If multiple "services" live in one service, this is the package where the service's Go files live (e.g., VPC is part of EC2)
file_prefix Code If multiple "services" live in one service, this is the prefix that files must have to be associated with this sub-service (e.g., VPC files in the EC2 service are prefixed with vpc_); see also split_packages_real_packages
doc_prefix Code Hcl string list of prefixes for service documentation files in website/docs/r and website/docs/d; usually only one prefix, i.e., <provider_package_correct>_
brand Code Either Amazon, AWS, or blank (rare) as used by AWS; used in error messages
exclude Code Bool based on whether the service should be included; if included (blank), ProviderPackageActual or provider_package_correct must have a value
allowed_subcategory Code Bool based on if Exclude is non-blank, whether to include human_friendly in website/allowed-subcategories.txt anyway. In other words, if non-blank, overrides exclude in some situations. Some excluded pseudo-services (e.g., VPC is part of EC2) are still subcategories. Only applies if Exclude is non-blank.
not_implemented Code Bool based on whether the service is implemented by the provider
note Reference Very brief note usually to explain why excluded

For more information about service naming, see the Naming Guide.