config

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2021 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CompareConfig 

type CompareConfig struct {
	// Ignore is a list of field paths to ignore when comparing two objects
	Ignore []string `json:"ignore"`
}

CompareConfig informs instruct the code generator on how to compare two different two objects of the same type

type Config 

type Config struct {
	// Resources contains generator instructions for individual CRDs within an
	// API
	Resources map[string]ResourceConfig `json:"resources"`
	// CRDs to ignore. ACK generator would skip these resources.
	Ignore IgnoreSpec `json:"ignore"`
	// Contains generator instructions for individual API operations.
	Operations map[string]OperationConfig `json:"operations"`
	// PrefixConfig contains the prefixes to access certain fields in the generated
	// Go code.
	PrefixConfig PrefixConfig `json:"prefix_config,omitempty"`
	// IncludeACKMetadata lets you specify whether ACK Metadata should be included
	// in the status. Default is true.
	IncludeACKMetadata bool `json:"include_ack_metadata,omitempty"`
	// SetManyOutputNotFoundErrReturn is the return statement when generated
	// SetManyOutput function fails with NotFound error.
	// Default is "return nil, ackerr.NotFound"
	SetManyOutputNotFoundErrReturn string `json:"set_many_output_notfound_err_return,omitempty"`
}

Config represents instructions to the ACK code generator for a particular AWS service API

func New 

func New(
	configPath string,
	defaultConfig Config,
) (Config, error)

New returns a new Config object given a supplied path to a config file

func (*Config) GetCompareIgnoredFields 

func (c *Config) GetCompareIgnoredFields(resName string) []string

GetCompareIgnoredFields returns the list of field path to ignore when comparing two differnt objects

func (*Config) IsIgnoredOperation 

func (c *Config) IsIgnoredOperation(operation *awssdkmodel.Operation) bool

IsIgnoredOperation returns true if Operation Name is configured to be ignored in generator config for the AWS service

func (*Config) IsIgnoredResource 

func (c *Config) IsIgnoredResource(resourceName string) bool

IsIgnoredResource returns true if Operation Name is configured to be ignored in generator config for the AWS service

func (*Config) ListOpMatchFieldNames 

func (c *Config) ListOpMatchFieldNames(
	resName string,
) []string

ListOpMatchFieldNames returns a slice of strings representing the field names in the List operation's Output shape's element Shape that we should check a corresponding value in the target Spec exists.

func (*Config) OverrideValues 

func (c *Config) OverrideValues(operationName string) (map[string]string, bool)

OverrideValues gives list of member values to override.

func (*Config) ResourceConfig added in v0.0.2 

func (c *Config) ResourceConfig(name string) (*ResourceConfig, bool)

ResourceConfig returns the ResourceConfig for a given named resource

func (*Config) ResourceFields added in v0.0.2 

func (c *Config) ResourceFields(resourceName string) map[string]*FieldConfig

ResourceFields returns a map, keyed by target/renamed field name, of FieldConfig struct pointers that instruct the code generator how to handle the interpretation of special Resource fields (both Spec and Status)

func (*Config) ResourceInputFieldRename 

func (c *Config) ResourceInputFieldRename(
	resName string,
	opID string,
	origFieldName string,
) (string, bool)

ResourceInputFieldRename returns the renamed field for a Resource, a supplied Operation ID and original field name and whether or not a renamed override field name was found

func (*Config) ResourceShortNames added in v0.0.2 

func (c *Config) ResourceShortNames(resourceName string) []string

ResourceShortNames returns the CRD list of aliases

func (*Config) SetAttributesSingleAttribute 

func (c *Config) SetAttributesSingleAttribute(resourceName string) bool

SetAttributesSingleAttribute returns true if the supplied resource name has a SetAttributes operation that only actually changes a single attribute at a time. See: SNS SetTopicAttributes API call, which is entirely different from the SNS SetPlatformApplicationAttributes API call, which sets multiple attributes at once. :shrug:

func (*Config) UnpacksAttributesMap 

func (c *Config) UnpacksAttributesMap(resourceName string) bool

UnpacksAttributesMap returns true if the underlying API has Get{Resource}Attributes/Set{Resource}Attributes API calls that map real, schema'd fields to a raw `map[string]*string` for this resource (see SNS and SQS APIs)

type ErrorConfig added in v0.0.2 

type ErrorConfig struct {
	// Code corresponds to name of Exception returned by AWS API.
	// In AWS Go SDK terms - awsErr.Code()
	Code string `json:"code"`
	// MessagePrefix is an optional string field to be checked as prefix of the
	// exception message in addition to exception name. This is needed for HTTP codes
	// where the exception name alone is not sufficient to determine the type of error.
	// Example: SageMaker service throws ValidationException if job does not exist
	// as well as if IAM role does not have sufficient permission to fetch the dataset
	// For the former controller should proceed with creation of job whereas the
	// later is a terminal state.
	// In Go SDK terms - awsErr.Message()
	MessagePrefix *string `json:"message_prefix,omitempty"`
}

ErrorConfig contains instructions to the code generator about the exception corresponding to a HTTP status code

type ExceptionsConfig 

type ExceptionsConfig struct {
	// Errors is a map of HTTP status code to information about the Exception
	// that corresponds to that HTTP status code for this resource
	Errors map[int]ErrorConfig `json:"errors"`
	// Set of aws exception codes that are terminal exceptions for this resource
	TerminalCodes []string `json:"terminal_codes"`
}

ExceptionsConfig contains instructions to the code generator about how to handle the exceptions for the operations on a resource. These instructions are necessary for those APIs where the API models do not contain any information about the HTTP status codes a particular exception has (or, like the EC2 API, where the API model has no information at all about error responses for any operation)

type FieldConfig 

type FieldConfig struct {
	// IsAttribute informs the code generator that this field is part of an
	// "Attributes Map".
	//
	// Some resources for some service APIs follow a pattern or using an
	// "Attributes" `map[string]*string` that contains real, schema'd fields of
	// the primary resource, and that those fields should be "unpacked" from
	// the raw map and into CRD's Spec and Status struct fields.
	IsAttribute bool `json:"is_attribute"`
	// IsReadOnly indicates the field's value can not be set by a Kubernetes
	// user; in other words, the field should go in the CR's Status struct
	IsReadOnly bool `json:"is_read_only"`
	// IsPrintable determines whether the field should be included in the
	// AdditionalPrinterColumns list to be included in the `kubectl get`
	// response.
	IsPrintable bool `json:"is_printable"`
	// Required indicates whether this field is a required member or not.
	// This field is used to configure '+kubebuilder:validation:Required' on API object's members.
	IsRequired *bool `json:"is_required,omitempty"`
	// IsName indicates the field represents the name/string identifier field
	// for the resource.  This allows the generator config to override the
	// default behaviour of considering a field called "Name" or
	// "{Resource}Name" or "{Resource}Id" as the "name field" for the resource.
	IsName bool `json:"is_name"`
	// IsOwnerAccountID indicates the field contains the AWS Account ID
	// that owns the resource. This is a special field that we direct to
	// storage in the common `Status.ACKResourceMetadata.OwnerAccountID` field.
	IsOwnerAccountID bool `json:"is_owner_account_id"`
	// From instructs the code generator that the value of the field should
	// be retrieved from the specified operation and member path
	From *SourceFieldConfig `json:"from,omitempty"`
}

FieldConfig contains instructions to the code generator about how to interpret the value of an Attribute and how to map it to a CRD's Spec or Status field

type GetAttributesInputConfig 

type GetAttributesInputConfig struct {
	// Overrides is a map of structures instructing the code generator how to
	// handle the override of a particular field in the Input shape for the
	// GetAttributes operation. The map keys are the names of the field in the
	// Input shape to override.
	Overrides map[string]*MemberConstructorConfig `json:"overrides"`
}

GetAttributesInputConfig is used to instruct the code generator how to handle the GetAttributes API operation's Input shape.

type IgnoreSpec 

type IgnoreSpec struct {
	// Set of operation IDs/names that should be ignored by the
	// generator when constructing SDK linkage
	Operations []string `json:"operations"`
	// Set of resource names that should be ignored by the
	// generator
	ResourceNames []string `json:"resource_names"`
	// Set of shapes to ignore when constructing API type definitions and
	// associated SDK code for structs that have these shapes as members
	ShapeNames []string `json:"shape_names"`
	// Set of field paths to ignore. The name here should be the original name of
	// the field as it appears in AWS SDK objects. You can refer to a field by
	// giving its "<shape_name>.<field_name>". For example, "CreateApiInput.Name".
	FieldPaths []string `json:"field_paths"`
}

IgnoreSpec represents instructions to the ACK code generator to ignore operations, resources on an AWS service API

type ListOperationConfig 

type ListOperationConfig struct {
	// MatchFields lists the names of fields in the Shape of the
	// list element in the List Operation's Output shape.
	MatchFields []string `json:"match_fields"`
}

ListOperationConfig contains instructions for the code generator to handle List operations for service APIs that have no built-in filtering ability and whose List Operation always returns all objects.

type MemberConstructorConfig 

type MemberConstructorConfig struct {
	// Values contains the value or values of the member to always set the
	// member to. If the member's type is a []string, the member is set to the
	// Values list. If the type is a string, the member's value is set to the
	// first list element in the Values list.
	Values []string `json:"values"`
}

MemberConstructorConfig contains override instructions for how to handle the construction of a particular member for a Shape in the API.

type OperationConfig 

type OperationConfig struct {
	CustomImplementation string            `json:"custom_implementation,omitempty"`
	OverrideValues       map[string]string `json:"override_values"`
	// SetOutputCustomMethodName provides the name of the custom method on the
	// `resourceManager` struct that will set fields on a `resource` struct
	// depending on the output of the operation.
	SetOutputCustomMethodName string `json:"set_output_custom_method_name,omitempty"`
	// Override for resource name in case of heuristic failure
	// An example of this is correcting stutter when the resource logic doesn't properly determine the resource name
	ResourceName string `json:"resource_name"`
	// Override for operation type in case of heuristic failure
	// An example of this is `Put...` or `Register...` API operations not being correctly classified as `Create` op type
	OperationType string `json:"operation_type"`
}

OperationConfig represents instructions to the ACK code generator to specify the overriding values for API operation parameters and its custom implementation.

type OperationRenamesConfig 

type OperationRenamesConfig struct {
	// InputFields is a map of Input shape fields to renamed field name.
	InputFields map[string]string `json:"input_fields"`
	// OutputFields is a map of Output shape fields to renamed field name.
	OutputFields map[string]string `json:"output_fields"`
}

OperationRenamesConfig contains instructions to the code generator on how to rename fields in an Operation's input and output payload shapes

type PrefixConfig 

type PrefixConfig struct {
	// SpecField stores the string prefix to use for information that will be
	// sent to AWS. Defaults to `.Spec`
	SpecField string `json:"spec_field,omitempty"`
	// StatusField stores the string prefix to use for information fetched from
	// AWS. Defaults to `.Status`
	StatusField string `json:"status_field,omitempty"`
}

type RenamesConfig 

type RenamesConfig struct {
	// Operations is a map, keyed by Operation ID, of instructions on how to
	// handle renamed fields in Input and Output shapes.
	Operations map[string]*OperationRenamesConfig `json:"operations"`
}

RenamesConfig contains instructions to the code generator how to rename fields in various Operation payloads

type ResourceConfig 

type ResourceConfig struct {
	// UnpackAttributeMapConfig contains instructions for converting a raw
	// `map[string]*string` into real fields on a CRD's Spec or Status object
	UnpackAttributesMapConfig *UnpackAttributesMapConfig `json:"unpack_attributes_map,omitempty"`
	// Exceptions identifies the exception codes for the resource. Some API
	// model files don't contain the ErrorInfo struct that contains the
	// HTTPStatusCode attribute that we usually look for to identify 404 Not
	// Found and other common error types for primary resources, and thus we
	// need these instructions.
	Exceptions *ExceptionsConfig `json:"exceptions,omitempty"`

	// Renames identifies fields in Operations that should be renamed.
	Renames *RenamesConfig `json:"renames,omitempty"`
	// ListOperation contains instructions for the code generator to generate
	// Go code that filters the results of a List operation looking for a
	// singular object. Certain AWS services (e.g. S3's ListBuckets API) have
	// absolutely no way to pass a filter to the operation. Instead, the List
	// operation always returns ALL objects of that type.
	//
	// The ListOperationConfig object enables us to inject some custom code to
	// filter the results of these List operations from within the generated
	// code in sdk.go's sdkFind().
	ListOperation *ListOperationConfig `json:"list_operation,omitempty"`
	// UpdateOperation contains instructions for the code generator to generate
	// Go code for the update operation for the resource. For some APIs, the
	// way that a resource's attributes are updated after creation is, well,
	// very odd. Some APIs have separate API calls for each attribute or set of
	// related attributes of the resource. For example, the ECR API has
	// separate API calls for PutImageScanningConfiguration,
	// PutImageTagMutability, PutLifecyclePolicy and SetRepositoryPolicy. FOr
	// these APIs, we basically need to revert to custom code because there's
	// very little consistency to the APIs that we can use to instruct the code
	// generator :(
	UpdateOperation *UpdateOperationConfig `json:"update_operation,omitempty"`
	// UpdateConditionsCustomMethodName provides the name of the custom method on the
	// `resourceManager` struct that will set Conditions on a `resource` struct
	// depending on the status of the resource.
	UpdateConditionsCustomMethodName string `json:"update_conditions_custom_method_name,omitempty"`
	// Fields is a map, keyed by the field name, of instructions for how the
	// code generator should interpret and handle a particular field in the
	// resource.
	Fields map[string]*FieldConfig `json:"fields"`
	// Compare contains instructions for the code generation to generate custom
	// comparison logic.
	Compare *CompareConfig `json:"compare,omitempty"`
	// ShortNames represent the CRD list of aliases. Short names allow shorter strings to
	// match a CR on the CLI.
	// All ShortNames must be distinct from any other ShortNames installed into the cluster,
	// otherwise the CRD will fail to install.
	ShortNames []string `json:"shortNames,omitempty"`
}

ResourceConfig represents instructions to the ACK code generator for a particular CRD/resource on an AWS service API

type SourceFieldConfig added in v0.0.2 

type SourceFieldConfig struct {
	// Operation refers to the ID of the API Operation where we will
	// determine the field's Go type.
	Operation string `json:"operation"`
	// Path refers to the field path of the member of the Input or Output
	// shape in the Operation identified by OperationID that we will take as
	// our additional spec/status field's value.
	Path string `json:"path"`
}

SourceFieldConfig instructs the code generator how to handle a field in the Resource's SpecFields/StatusFields collection that takes its value from an abnormal source -- in other words, not the Create operation's Input or Output shape.

This additional field can source its value from a shape in a different API Operation entirely.

The data type (Go type) that a field is assigned during code generation depends on whether the field is part of the Create Operation's Input shape which go into the Resource's Spec fields collection, or the Create Operation's Output shape which, if not present in the Input shape, means the field goes into the Resource's Status fields collection).

Each Resource typically also has a ReadOne Operation. The ACK service controller will call this ReadOne Operation to get the latest observed state of a particular resource in the backend AWS API service. The service controller sets the observed Resource's Spec and Status fields from the Output shape of the ReadOne Operation. The code generator is responsible for producing the Go code that performs these "setter" methods on the Resource. The way the code generator determines how to set the Spec or Status fields from the Output shape's member fields is by looking at the data type of the Spec or Status field with the same name as the Output shape's member field.

Importantly, in producing this "setter" Go code the code generator **assumes that the data types (Go types) in the source (the Output shape's member field) and target (the Spec or Status field) are the same**.

There are some APIs, however, where the Go type of the field in the Create Operation's Input shape is actually different from the same-named field in the ReadOne Operation's Output shape. A good example of this is the Lambda CreateFunction API call, which has a `Code` member of its Input shape that looks like this: 

"Code": {
  "ImageUri": "string",
  "S3Bucket": "string",
  "S3Key": "string",
  "S3ObjectVersion": "string",
  "ZipFile": blob
},

The GetFunction API call's Output shape has a same-named field called `Code` in it, but this field looks like this: 

"Code": {
  "ImageUri": "string",
  "Location": "string",
  "RepositoryType": "string",
  "ResolvedImageUri": "string"
},

This presents a conundrum to the ACK code generator, which, as noted above, assumes the data types of same-named fields in the Create Operation's Input shape and ReadOne Operation's Output shape are the same.

The SourceFieldConfig struct allows us to explain to the code generator how to handle situations like this.

For the Lambda Function Resource's `Code` field, we can inform the code generator to create three new Status fields (readonly) from the `Location`, `RepositoryType` and `ResolvedImageUri` fields in the `Code` member of the ReadOne Operation's Output shape:

resources: 

Function:
  fields:
    CodeLocation:
      is_read_only: true
      from:
        operation: GetFunction
        path: Code.Location
    CodeRepositoryType:
      is_read_only: true
      from:
        operation: GetFunction
        path: Code.RepositoryType
    CodeRegisteredImageURI:
      is_read_only: true
      from:
        operation: GetFunction
        path: Code.RegisteredImageUri

type UnpackAttributesMapConfig 

type UnpackAttributesMapConfig struct {
	// SetAttributesSingleAttribute indicates that the SetAttributes API call
	// doesn't actually set multiple attributes but rather must be called
	// multiple times, once for each attribute that needs to change. See SNS
	// SetTopicAttributes API call, which can be compared to the "normal" SNS
	// SetPlatformApplicationAttributes API call which accepts multiple
	// attributes and replaces the supplied attributes map key/values...
	SetAttributesSingleAttribute bool `json:"set_attributes_single_attribute"`
	// GetAttributesInput instructs the code generator how to handle the
	// GetAttributes input shape
	GetAttributesInput *GetAttributesInputConfig `json:"get_attributes_input,omitempty"`
}

UnpackAttributesMapConfig informs the code generator that the API follows a pattern or using an "Attributes" `map[string]*string` that contains real, schema'd fields of the primary resource, and that those fields should be "unpacked" from the raw map and into CRD's Spec and Status struct fields.

AWS Simple Notification Service (SNS) and AWS Simple Queue Service (SQS) are examples of APIs that use this pattern. For instance, the SNS CreateTopic API accepts a parameter called "Attributes" that can contain one of four keys:

  • DeliveryPolicy – The policy that defines how Amazon SNS retries failed deliveries to HTTP/S endpoints.
  • DisplayName – The display name to use for a topic with SMS subscriptions
  • Policy – The policy that defines who can access your topic.
  • KmsMasterKeyId - The ID of an AWS-managed customer master key (CMK) for Amazon SNS or a custom CMK.

The `CreateTopic` API call **returns** only a single field: the TopicARN. But there is a separate `GetTopicAttributes` call that needs to be made that returns the above attributes (that are ReadWrite) along with a set of key/values that are ReadOnly:

  • Owner – The AWS account ID of the topic's owner.
  • SubscriptionsConfirmed – The number of confirmed subscriptions for the topic.
  • SubscriptionsDeleted – The number of deleted subscriptions for the topic.
  • SubscriptionsPending – The number of subscriptions pending confirmation for the topic.
  • TopicArn – The topic's ARN.
  • EffectiveDeliveryPolicy – The JSON serialization of the effective delivery policy, taking system defaults into account.

This structure instructs the code generator about the above real, schema'd fields that are masquerading as raw key/value pairs.

type UpdateOperationConfig 

type UpdateOperationConfig struct {
	// CustomMethodName is a string for the method name to replace the
	// sdkUpdate() method implementation for this resource
	CustomMethodName string `json:"custom_method_name"`
}

UpdateOperationConfig contains instructions for the code generator to handle Update operations for service APIs that have resources that have difficult-to-standardize update operations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.