Consolidate service naming nomenclature (#213)

Issue #, if available: aws-controllers-k8s/community#994

Description of changes:
This pull request replaces all templates and variables with a defined nomenclature. The current code-generator uses service name terms interchangeably, which eventually lead to the linked issue. While PR #211 solved the logical issue of overriding the service model name, in some cases, it did not do a clear job of clarifying what names exist for any service and when they are applicable.

There are 3 different names that are used to programmatically reference a service. Here are the terms I am using in this PR to refer to them, and their given purpose:
- Service ID
  - The `metadata.serviceID` field from the model `api-2.json` file
- Service model name
  - The path to the model `api-2.json` file
- Service package name
  - The AWS SDK Go package path
  - Used by the ACK controller's for their name 

Some examples on when these differ:
- Step Functions uses `sfn` for its ID and alias, but `states` for its model name
- Elastic Load Balancing v2 uses `elbv2` for its alias, but `elasticloadbalancingv2` for its ID and model name

There are also 2 names defined in the controller metadata file that are not used in any parts of the code, but are used in documentation:
- Service name
  - The full name of the service as defined by the product's documentation page (eg. `Amazon Elastic Cloud Compute`)
-  Service short name
  - An informal, shortened name of the service (eg. `EC2`)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Author: RedbackThomson

cmd/ack-generate/command/crossplane.go

@@ -74,11 +74,12 @@ func generateCrossplane(_ *cobra.Command, args []string) error {
 	sdkHelper.APIGroupSuffix = "aws.crossplane.io"
 	sdkAPI, err := sdkHelper.API(svcAlias)
 	if err != nil {
-		newSvcAlias, err := FallBackFindServiceID(sdkDir, svcAlias)
+		retryModelName, err := FallBackFindServiceID(sdkDir, svcAlias)
 		if err != nil {
 			return err
 		}
-		sdkAPI, err = sdkHelper.API(newSvcAlias) // retry with serviceID
+		// Retry using path found by querying service ID
+		sdkAPI, err = sdkHelper.API(retryModelName)
 		if err != nil {
 			return fmt.Errorf("cannot get the API model for service %s", svcAlias)
 		}

cmd/ack-generate/command/olm.go

@@ -42,7 +42,7 @@ var olmCmd = &cobra.Command{
 	Short: `Generate an Operator Lifecycle Manager's ClusterServiceVersion
 resources for AWS service API. Expects a configuration file to be passed in
 via the --olm-config option, or otherwise reads the config at the root of the
-project with the filename <servicealias>-olmconfig.yaml`,
+project with the filename <servicepackage>-olmconfig.yaml`,
 	RunE: generateOLMAssets,
 }
 

pkg/generate/crossplane/crossplane.go

@@ -145,7 +145,7 @@ func Crossplane(
 	for _, path := range apisGenericTemplatesPaths {
 		outPath := filepath.Join(
 			"apis",
-			metaVars.ServiceAlias,
+			metaVars.ServicePackageName,
 			metaVars.APIVersion,
 			"zz_"+strings.TrimSuffix(filepath.Base(path), ".tpl"),
 		)
@@ -155,7 +155,7 @@ func Crossplane(
 	}
 	for _, crd := range crds {
 		crdFileName := filepath.Join(
-			"apis", metaVars.ServiceAlias, metaVars.APIVersion,
+			"apis", metaVars.ServicePackageName, metaVars.APIVersion,
 			"zz_"+strcase.ToSnake(crd.Kind)+".go",
 		)
 		crdVars := &templateCRDVars{
@@ -170,7 +170,7 @@ func Crossplane(
 	// Next add the controller package for each CRD
 	for _, crd := range crds {
 		outPath := filepath.Join(
-			"pkg", "controller", metaVars.ServiceAlias, crd.Names.Lower,
+			"pkg", "controller", metaVars.ServicePackageName, crd.Names.Lower,
 			"zz_controller.go",
 		)
 		crdVars := &templateCRDVars{
@@ -181,7 +181,7 @@ func Crossplane(
 			return nil, err
 		}
 		outPath = filepath.Join(
-			"pkg", "controller", metaVars.ServiceAlias, crd.Names.Lower,
+			"pkg", "controller", metaVars.ServicePackageName, crd.Names.Lower,
 			"zz_conversions.go",
 		)
 		crdVars = &templateCRDVars{

pkg/generate/olm/olm.go

@@ -79,7 +79,7 @@ func BundleAssets(
 
 	csvBaseOutPath := fmt.Sprintf(
 		"config/manifests/bases/ack-%s-controller.clusterserviceversion.yaml",
-		m.MetaVars().ServiceAlias)
+		m.MetaVars().ServicePackageName)
 	if err := ts.Add(csvBaseOutPath, "config/manifests/bases/clusterserviceversion.yaml.tpl", olmVars); err != nil {
 		return nil, err
 	}

pkg/generate/templateset/vars.go

@@ -16,28 +16,28 @@ package templateset
 // MetaVars contains template variables that most templates need access to
 // that describe the service alias, its package name, etc
 type MetaVars struct {
-	// ServiceAlias contains the exact string used to identify the AWS service
-	// API in the aws-sdk-go `service/` directory. It is also used as the
-	// identifier for the ACK controller's name and packages.
-	ServiceAlias string
-	// ServiceID is the exact string that appears in the AWS service API's
-	// api-2.json descriptor file under `metadata.serviceId`
-	ServiceID string
 	// ServiceModelName contains the exact string used to identify the AWS
 	// service API in the aws-sdk-go's models/apis/ directory. Note that some
 	// APIs this name does not match the ServiceID. e.g. The AWS Step Functions
 	// API has a ServiceID of "SFN" and a service model name of "states"...
 	ServiceModelName string
+	// ServicePackageName contains the exact string used to identify the AWS
+	// service API in the aws-sdk-go `service/` directory. It is also used as
+	// the identifier for the ACK controller's name and packages.
+	ServicePackageName string
+	// ServiceID is the exact string that appears in the AWS service API's
+	// api-2.json descriptor file under `metadata.serviceId`
+	ServiceID string
 	// APIVersion contains the version of the Kubernetes API resources, e.g.
 	// "v1alpha1"
 	APIVersion string
 	// APIGroup contains the normalized name of the Kubernetes APIGroup used
 	// for custom resources, e.g. "sns.services.k8s.aws" or
 	// "sfn.services.k8s.aws"
 	APIGroup string
-	// SDKAPIInterfaceTypeName is the name of the interface type used by the
+	// APIInterfaceTypeName is the name of the interface type used by the
 	// aws-sdk-go services/$SERVICE/api.go file
-	SDKAPIInterfaceTypeName string
+	APIInterfaceTypeName string
 	//CRDNames contains all crds names lowercased and in plural
 	CRDNames []string
 }

pkg/model/model.go

@@ -34,13 +34,13 @@ var (
 // Model contains the ACK model for the generator to process and apply
 // templates against.
 type Model struct {
-	SDKAPI       *SDKAPI
-	serviceAlias string
-	apiVersion   string
-	crds         []*CRD
-	typeDefs     []*TypeDef
-	typeImports  map[string]string
-	typeRenames  map[string]string
+	SDKAPI             *SDKAPI
+	servicePackageName string
+	apiVersion         string
+	crds               []*CRD
+	typeDefs           []*TypeDef
+	typeImports        map[string]string
+	typeRenames        map[string]string
 	// Instructions to the code generator how to handle the API and its
 	// resources
 	cfg *ackgenconfig.Config
@@ -50,13 +50,13 @@ type Model struct {
 // service API
 func (m *Model) MetaVars() templateset.MetaVars {
 	return templateset.MetaVars{
-		ServiceAlias:            m.serviceAlias,
-		ServiceID:               m.SDKAPI.ServiceID(),
-		ServiceModelName:        m.cfg.ModelName,
-		APIGroup:                m.APIGroup(),
-		APIVersion:              m.apiVersion,
-		SDKAPIInterfaceTypeName: m.SDKAPI.SDKAPIInterfaceTypeName(),
-		CRDNames:                m.crdNames(),
+		ServicePackageName:   m.servicePackageName,
+		ServiceID:            m.SDKAPI.ServiceID(),
+		ServiceModelName:     m.cfg.ModelName,
+		APIGroup:             m.APIGroup(),
+		APIVersion:           m.apiVersion,
+		APIInterfaceTypeName: m.SDKAPI.APIInterfaceTypeName(),
+		CRDNames:             m.crdNames(),
 	}
 }
 
@@ -694,28 +694,27 @@ func (m *Model) GetConfig() *ackgenconfig.Config {
 // APIGroup returns the normalized Kubernetes APIGroup for the AWS service API,
 // e.g. "sns.services.k8s.aws"
 func (m *Model) APIGroup() string {
-	serviceAlias := m.serviceAlias
 	suffix := "services.k8s.aws"
 	if m.SDKAPI.apiGroupSuffix != "" {
 		suffix = m.SDKAPI.apiGroupSuffix
 	}
-	return fmt.Sprintf("%s.%s", serviceAlias, suffix)
+	return fmt.Sprintf("%s.%s", m.servicePackageName, suffix)
 }
 
 // New returns a new Model struct for a supplied API model.
 // Optionally, pass a file path to a generator config file that can be used to
 // instruct the code generator how to handle the API properly
 func New(
 	SDKAPI *SDKAPI,
-	serviceAlias string,
+	servicePackageName string,
 	apiVersion string,
 	cfg ackgenconfig.Config,
 ) (*Model, error) {
 	m := &Model{
-		SDKAPI:       SDKAPI,
-		serviceAlias: serviceAlias,
-		apiVersion:   apiVersion,
-		cfg:          &cfg,
+		SDKAPI:             SDKAPI,
+		servicePackageName: servicePackageName,
+		apiVersion:         apiVersion,
+		cfg:                &cfg,
 	}
 	m.ApplyShapeIgnoreRules()
 	return m, nil

pkg/model/multiversion/manager.go

@@ -50,7 +50,7 @@ type APIVersionManager struct {
 func NewAPIVersionManager(
 	sdkCacheDir string,
 	metadataPath string,
-	serviceAlias string,
+	servicePackageName string,
 	hubVersion string,
 	apisInfo map[string]ackmetadata.APIInfo,
 	defaultConfig ackgenconfig.Config,
@@ -99,14 +99,14 @@ func NewAPIVersionManager(
 			return nil, err
 		}
 
-		SDKAPI, err := SDKAPIHelper.API(serviceAlias)
+		SDKAPI, err := SDKAPIHelper.API(servicePackageName)
 		if err != nil {
 			return nil, err
 		}
 
 		i, err := ackmodel.New(
 			SDKAPI,
-			serviceAlias,
+			servicePackageName,
 			version.APIVersion,
 			cfg,
 		)

pkg/model/sdk_helper.go

@@ -139,8 +139,8 @@ func (h *SDKHelper) ModelAndDocsPath(
 
 // FirstAPIVersion returns the first found API version for a service API.
 // (e.h. "2012-10-03")
-func (h *SDKHelper) FirstAPIVersion(serviceAlias string) (string, error) {
-	versions, err := h.GetAPIVersions(serviceAlias)
+func (h *SDKHelper) FirstAPIVersion(serviceModelName string) (string, error) {
+	versions, err := h.GetAPIVersions(serviceModelName)
 	if err != nil {
 		return "", err
 	}
@@ -149,8 +149,8 @@ func (h *SDKHelper) FirstAPIVersion(serviceAlias string) (string, error) {
 }
 
 // GetAPIVersions returns the list of API Versions found in a service directory.
-func (h *SDKHelper) GetAPIVersions(serviceAlias string) ([]string, error) {
-	apiPath := filepath.Join(h.basePath, "models", "apis", serviceAlias)
+func (h *SDKHelper) GetAPIVersions(serviceModelName string) ([]string, error) {
+	apiPath := filepath.Join(h.basePath, "models", "apis", serviceModelName)
 	versionDirs, err := ioutil.ReadDir(apiPath)
 	if err != nil {
 		return nil, err
@@ -354,30 +354,26 @@ func (a *SDKAPI) HasConflictingTypeName(typeName string, cfg *ackgenconfig.Confi
 }
 
 // ServiceID returns the exact `metadata.serviceId` attribute for the AWS
-// service APi's api-2.json file
+// service APi's api-2.json file.
+// This MAY NOT MATCH the AWS SDK Go package used by the service. For example:
+// AWS SDK Go uses `opensearchservice` whereas the service ID is `opensearch`
 func (a *SDKAPI) ServiceID() string {
 	if a == nil || a.API == nil {
 		return ""
 	}
 	return awssdkmodel.ServiceID(a.API)
 }
 
-// ServiceIDClean returns a lowercased, whitespace-stripped ServiceID
-func (a *SDKAPI) ServiceIDClean() string {
-	serviceID := strings.ToLower(a.ServiceID())
-	return strings.Replace(serviceID, " ", "", -1)
-}
-
 func (a *SDKAPI) GetServiceFullName() string {
 	if a == nil || a.API == nil {
 		return ""
 	}
 	return a.API.Metadata.ServiceFullName
 }
 
-// SDKAPIInterfaceTypeName returns the name of the aws-sdk-go primary API
+// APIInterfaceTypeName returns the name of the aws-sdk-go primary API
 // interface type name.
-func (a *SDKAPI) SDKAPIInterfaceTypeName() string {
+func (a *SDKAPI) APIInterfaceTypeName() string {
 	if a == nil || a.API == nil {
 		return ""
 	}

pkg/testutil/schema_helper.go

@@ -50,12 +50,12 @@ func (o *TestingModelOptions) SetDefaults() {
 }
 
 // NewModelForService returns a new *ackmodel.Model used for testing purposes.
-func NewModelForService(t *testing.T, serviceAlias string) *ackmodel.Model {
-	return NewModelForServiceWithOptions(t, serviceAlias, &TestingModelOptions{})
+func NewModelForService(t *testing.T, servicePackageName string) *ackmodel.Model {
+	return NewModelForServiceWithOptions(t, servicePackageName, &TestingModelOptions{})
 }
 
 // NewModelForServiceWithOptions returns a new *ackmodel.Model used for testing purposes.
-func NewModelForServiceWithOptions(t *testing.T, serviceAlias string, options *TestingModelOptions) *ackmodel.Model {
+func NewModelForServiceWithOptions(t *testing.T, servicePackageName string, options *TestingModelOptions) *ackmodel.Model {
 	path, err := os.Getwd()
 	if err != nil {
 		t.Fatal(err)
@@ -75,19 +75,19 @@ func NewModelForServiceWithOptions(t *testing.T, serviceAlias string, options *T
 	options.SetDefaults()
 	sdkHelper := model.NewSDKHelper(path)
 	sdkHelper.WithAPIVersion(options.ServiceAPIVersion)
-	sdkAPI, err := sdkHelper.API(serviceAlias)
+	sdkAPI, err := sdkHelper.API(servicePackageName)
 	if err != nil {
 		t.Fatal(err)
 	}
-	generatorConfigPath := filepath.Join(path, "models", "apis", serviceAlias, options.ServiceAPIVersion, options.GeneratorConfigFile)
+	generatorConfigPath := filepath.Join(path, "models", "apis", servicePackageName, options.ServiceAPIVersion, options.GeneratorConfigFile)
 	if _, err := os.Stat(generatorConfigPath); os.IsNotExist(err) {
 		generatorConfigPath = ""
 	}
 	cfg, err := ackgenconfig.New(generatorConfigPath, ackgenerate.DefaultConfig)
 	if err != nil {
 		t.Fatal(err)
 	}
-	m, err := ackmodel.New(sdkAPI, serviceAlias, options.APIVersion, cfg)
+	m, err := ackmodel.New(sdkAPI, servicePackageName, options.APIVersion, cfg)
 	if err != nil {
 		t.Fatal(err)
 	}

templates/cmd/controller/main.go.tpl

@@ -14,19 +14,19 @@ import (
 	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
 	ctrlrt "sigs.k8s.io/controller-runtime"
 	ctrlrtmetrics "sigs.k8s.io/controller-runtime/pkg/metrics"
-	svcsdk "github.com/aws/aws-sdk-go/service/{{ .ServiceAlias }}"
+	svcsdk "github.com/aws/aws-sdk-go/service/{{ .ServicePackageName }}"
 
 	ackv1alpha1 "github.com/aws-controllers-k8s/runtime/apis/core/v1alpha1"
-	svcresource "github.com/aws-controllers-k8s/{{ .ServiceAlias }}-controller/pkg/resource"
-	svctypes "github.com/aws-controllers-k8s/{{ .ServiceAlias }}-controller/apis/{{ .APIVersion }}"
+	svcresource "github.com/aws-controllers-k8s/{{ .ServicePackageName }}-controller/pkg/resource"
+	svctypes "github.com/aws-controllers-k8s/{{ .ServicePackageName }}-controller/apis/{{ .APIVersion }}"
 	{{/* TODO(a-hilaly): import apis/* packages to register webhooks */}}
-	{{ $serviceIDClean := .ServiceAlias }} {{range $crdName := .SnakeCasedCRDNames }}_ "github.com/aws-controllers-k8s/{{ $serviceIDClean }}-controller/pkg/resource/{{ $crdName }}"
+	{{ $serviceAlias := .ServicePackageName }} {{range $crdName := .SnakeCasedCRDNames }}_ "github.com/aws-controllers-k8s/{{ $serviceAlias }}-controller/pkg/resource/{{ $crdName }}"
 	{{end}}
 )
 
 var (
 	awsServiceAPIGroup = "{{ .APIGroup }}"
-	awsServiceAlias	= "{{ .ServiceAlias }}"
+	awsServiceAlias	= "{{ .ServicePackageName }}"
 	awsServiceEndpointsID = svcsdk.EndpointsID
 	scheme			 = runtime.NewScheme()
 	setupLog		   = ctrlrt.Log.WithName("setup")