crd_mapping.go

Documentation: github.com/datawire/ambassador/v2/pkg/api/getambassador.io/v3alpha1

     1  // Copyright 2020 Datawire.  All rights reserved
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  ///////////////////////////////////////////////////////////////////////////
    16  // Important: Run "make generate-fast" to regenerate code after modifying
    17  // this file.
    18  ///////////////////////////////////////////////////////////////////////////
    19  
    20  package v3alpha1
    21  
    22  import (
    23  	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    24  )
    25  
    26  // MappingSpec defines the desired state of Mapping
    27  type MappingSpec struct {
    28  	AmbassadorID AmbassadorID `json:"ambassador_id,omitempty"`
    29  
    30  	// +kubebuilder:validation:Required
    31  	Prefix      string `json:"prefix,omitempty"`
    32  	PrefixRegex *bool  `json:"prefix_regex,omitempty"`
    33  	PrefixExact *bool  `json:"prefix_exact,omitempty"`
    34  	// +kubebuilder:validation:Required
    35  	Service            string                  `json:"service,omitempty"`
    36  	AddRequestHeaders  *map[string]AddedHeader `json:"add_request_headers,omitempty"`
    37  	AddResponseHeaders *map[string]AddedHeader `json:"add_response_headers,omitempty"`
    38  	AddLinkerdHeaders  *bool                   `json:"add_linkerd_headers,omitempty"`
    39  	AutoHostRewrite    *bool                   `json:"auto_host_rewrite,omitempty"`
    40  	CaseSensitive      *bool                   `json:"case_sensitive,omitempty"`
    41  	DNSType            string                  `json:"dns_type,omitempty"`
    42  	Docs               *DocsInfo               `json:"docs,omitempty"`
    43  	EnableIPv4         *bool                   `json:"enable_ipv4,omitempty"`
    44  	EnableIPv6         *bool                   `json:"enable_ipv6,omitempty"`
    45  	CircuitBreakers    []*CircuitBreaker       `json:"circuit_breakers,omitempty"`
    46  	KeepAlive          *KeepAlive              `json:"keepalive,omitempty"`
    47  	CORS               *CORS                   `json:"cors,omitempty"`
    48  	RetryPolicy        *RetryPolicy            `json:"retry_policy,omitempty"`
    49  	RespectDNSTTL      *bool                   `json:"respect_dns_ttl,omitempty"`
    50  	GRPC               *bool                   `json:"grpc,omitempty"`
    51  	HostRedirect       *bool                   `json:"host_redirect,omitempty"`
    52  	HostRewrite        string                  `json:"host_rewrite,omitempty"`
    53  	Method             string                  `json:"method,omitempty"`
    54  	MethodRegex        *bool                   `json:"method_regex,omitempty"`
    55  	OutlierDetection   string                  `json:"outlier_detection,omitempty"`
    56  	// Path replacement to use when generating an HTTP redirect. Used with `host_redirect`.
    57  	PathRedirect string `json:"path_redirect,omitempty"`
    58  	// Prefix rewrite to use when generating an HTTP redirect. Used with `host_redirect`.
    59  	PrefixRedirect string `json:"prefix_redirect,omitempty"`
    60  	// Prefix regex rewrite to use when generating an HTTP redirect. Used with `host_redirect`.
    61  	RegexRedirect *RegexMap `json:"regex_redirect,omitempty"`
    62  	// The response code to use when generating an HTTP redirect. Defaults to 301. Used with
    63  	// `host_redirect`.
    64  	// +kubebuilder:validation:Enum={301,302,303,307,308}
    65  	RedirectResponseCode         *int                 `json:"redirect_response_code,omitempty"`
    66  	Priority                     string               `json:"priority,omitempty"`
    67  	Precedence                   *int                 `json:"precedence,omitempty"`
    68  	ClusterTag                   string               `json:"cluster_tag,omitempty"`
    69  	RemoveRequestHeaders         *[]string            `json:"remove_request_headers,omitempty"`
    70  	RemoveResponseHeaders        *[]string            `json:"remove_response_headers,omitempty"`
    71  	Resolver                     string               `json:"resolver,omitempty"`
    72  	Rewrite                      *string              `json:"rewrite,omitempty"`
    73  	RegexRewrite                 *RegexMap            `json:"regex_rewrite,omitempty"`
    74  	Shadow                       *bool                `json:"shadow,omitempty"`
    75  	ConnectTimeout               *MillisecondDuration `json:"connect_timeout_ms,omitempty"`
    76  	ClusterIdleTimeout           *MillisecondDuration `json:"cluster_idle_timeout_ms,omitempty"`
    77  	ClusterMaxConnectionLifetime *MillisecondDuration `json:"cluster_max_connection_lifetime_ms,omitempty"`
    78  	// The timeout for requests that use this Mapping. Overrides `cluster_request_timeout_ms` set on the Ambassador Module, if it exists.
    79  	Timeout     *MillisecondDuration `json:"timeout_ms,omitempty"`
    80  	IdleTimeout *MillisecondDuration `json:"idle_timeout_ms,omitempty"`
    81  	TLS         string               `json:"tls,omitempty"`
    82  
    83  	// use_websocket is deprecated, and is equivlaent to setting
    84  	// `allow_upgrade: ["websocket"]`
    85  	//
    86  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.DeprecatedUseWebsocket.
    87  	DeprecatedUseWebsocket *bool `json:"use_websocket,omitempty"`
    88  
    89  	// A case-insensitive list of the non-HTTP protocols to allow
    90  	// "upgrading" to from HTTP via the "Connection: upgrade"
    91  	// mechanism[1].  After the upgrade, Ambassador does not
    92  	// interpret the traffic, and behaves similarly to how it does
    93  	// for TCPMappings.
    94  	//
    95  	// [1]: https://tools.ietf.org/html/rfc7230#section-6.7
    96  	//
    97  	// For example, if your upstream service supports WebSockets,
    98  	// you would write
    99  	//
   100  	//    allow_upgrade:
   101  	//    - websocket
   102  	//
   103  	// Or if your upstream service supports upgrading from HTTP to
   104  	// SPDY (as the Kubernetes apiserver does for `kubectl exec`
   105  	// functionality), you would write
   106  	//
   107  	//    allow_upgrade:
   108  	//    - spdy/3.1
   109  	AllowUpgrade []string `json:"allow_upgrade,omitempty"`
   110  
   111  	Weight                *int              `json:"weight,omitempty"`
   112  	BypassAuth            *bool             `json:"bypass_auth,omitempty"`
   113  	AuthContextExtensions map[string]string `json:"auth_context_extensions,omitempty"`
   114  	// If true, bypasses any `error_response_overrides` set on the Ambassador module.
   115  	BypassErrorResponseOverrides *bool `json:"bypass_error_response_overrides,omitempty"`
   116  	// Error response overrides for this Mapping. Replaces all of the `error_response_overrides`
   117  	// set on the Ambassador module, if any.
   118  	// +kubebuilder:validation:MinItems=1
   119  	ErrorResponseOverrides []ErrorResponseOverride `json:"error_response_overrides,omitempty"`
   120  	Modules                []UntypedDict           `json:"modules,omitempty"`
   121  
   122  	// Exact match for the hostname of a request if HostRegex is false; regex match for the
   123  	// hostname if HostRegex is true.
   124  	//
   125  	// Host specifies both a match for the ':authority' header of a request, as well as a match
   126  	// criterion for Host CRDs: a Mapping that specifies Host will not associate with a Host that
   127  	// doesn't have a matching Hostname.
   128  	//
   129  	// If both Host and Hostname are set, an error is logged, Host is ignored, and Hostname is
   130  	// used.
   131  	//
   132  	// DEPRECATED: Host is either an exact match or a regex, depending on HostRegex. Use HostName instead.
   133  	//
   134  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.host and MappingSpec.host_regex in
   135  	// favor of a MappingSpec.deprecated_hostname_regex.
   136  	DeprecatedHost string `json:"host,omitempty"`
   137  	// DEPRECATED: Host is either an exact match or a regex, depending on HostRegex. Use HostName instead.
   138  	//
   139  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.host and MappingSpec.host_regex in
   140  	// favor of a MappingSpec.deprecated_hostname_regex.
   141  	DeprecatedHostRegex *bool `json:"host_regex,omitempty"`
   142  	// Hostname is a DNS glob specifying the hosts to which this Mapping applies.
   143  	//
   144  	// Hostname specifies both a match for the ':authority' header of a request, as well as a
   145  	// match criterion for Host CRDs: a Mapping that specifies Hostname will not associate with
   146  	// a Host that doesn't have a matching Hostname.
   147  	//
   148  	// If both Host and Hostname are set, an error is logged, Host is ignored, and Hostname is
   149  	// used.
   150  	Hostname string `json:"hostname,omitempty"`
   151  
   152  	Headers              map[string]string `json:"headers,omitempty"`
   153  	RegexHeaders         map[string]string `json:"regex_headers,omitempty"`
   154  	Labels               DomainMap         `json:"labels,omitempty"`
   155  	EnvoyOverride        *UntypedDict      `json:"envoy_override,omitempty"`
   156  	LoadBalancer         *LoadBalancer     `json:"load_balancer,omitempty"`
   157  	QueryParameters      map[string]string `json:"query_parameters,omitempty"`
   158  	RegexQueryParameters map[string]string `json:"regex_query_parameters,omitempty"`
   159  	StatsName            string            `json:"stats_name,omitempty"`
   160  
   161  	V2ExplicitTLS         *V2ExplicitTLS `json:"v2ExplicitTLS,omitempty"`
   162  	V2BoolHeaders         []string       `json:"v2BoolHeaders,omitempty"`
   163  	V2BoolQueryParameters []string       `json:"v2BoolQueryParameters,omitempty"`
   164  }
   165  
   166  type RegexMap struct {
   167  	Pattern      string `json:"pattern,omitempty"`
   168  	Substitution string `json:"substitution,omitempty"`
   169  }
   170  
   171  // DocsInfo provides some extra information about the docs for the Mapping.
   172  // Docs is used by both the agent and the DevPortal.
   173  type DocsInfo struct {
   174  	Path        string               `json:"path,omitempty"`
   175  	URL         string               `json:"url,omitempty"`
   176  	Ignored     *bool                `json:"ignored,omitempty"`
   177  	DisplayName string               `json:"display_name,omitempty"`
   178  	Timeout     *MillisecondDuration `json:"timeout_ms,omitempty"`
   179  }
   180  
   181  // These are separate types partly because it makes it easier to think about
   182  // how `DomainMap` is built up, but also because it's pretty awful to read
   183  // a type definition that's four or five levels deep with maps and arrays.
   184  
   185  // A DomainMap is the overall Mapping.spec.Labels type. It maps domains (kind of
   186  // like namespaces for Mapping labels) to arrays of label groups.
   187  type DomainMap map[string]MappingLabelGroupsArray
   188  
   189  // A MappingLabelGroupsArray is an array of MappingLabelGroups. I know, complex.
   190  type MappingLabelGroupsArray []MappingLabelGroup
   191  
   192  // A MappingLabelGroup is a single element of a MappingLabelGroupsArray: a second
   193  // map, where the key is a human-readable name that identifies the group.
   194  //
   195  // +kubebuilder:validation:MinProperties=1
   196  // +kubebuilder:validation:MaxProperties=1
   197  type MappingLabelGroup map[string]MappingLabelsArray
   198  
   199  // A MappingLabelsArray is the value in the MappingLabelGroup: an array of label
   200  // specifiers.
   201  type MappingLabelsArray []MappingLabelSpecifier
   202  
   203  // A MappingLabelSpecifier (finally!) defines a single label.
   204  //
   205  // This mimics envoy/config/route/v3/route_components.proto:RateLimit:Action:action_specifier.
   206  //
   207  // +kubebuilder:validation:MinProperties=1
   208  // +kubebuilder:validation:MaxProperties=1
   209  type MappingLabelSpecifier struct {
   210  	// Sets the label "source_cluster=«Envoy source cluster name»".
   211  	SourceCluster *MappingLabelSpecifier_SourceCluster `json:"source_cluster,omitempty"`
   212  
   213  	// Sets the label "destination_cluster=«Envoy destination cluster name»".
   214  	DestinationCluster *MappingLabelSpecifier_DestinationCluster `json:"destination_cluster,omitempty"`
   215  
   216  	// If the «header_name» header is set, then set the label "«key»=«Value of the
   217  	// «header_name» header»"; otherwise skip applying this label group.
   218  	RequestHeaders *MappingLabelSpecifier_RequestHeaders `json:"request_headers,omitempty"`
   219  
   220  	// Sets the label "remote_address=«IP address of the client»".
   221  	RemoteAddress *MappingLabelSpecifier_RemoteAddress `json:"remote_address,omitempty"`
   222  
   223  	// Sets the label "«key»=«value»" (where by default «key»
   224  	// is "generic_key").
   225  	GenericKey *MappingLabelSpecifier_GenericKey `json:"generic_key,omitempty"`
   226  
   227  	// TODO: Consider implementing `header_value_match`, `metadata`, or `extension`?
   228  }
   229  
   230  type MappingLabelSpecifier_SourceCluster struct {
   231  	// +kubebuilder:validation:Enum={"source_cluster"}
   232  	// +kubebuilder:validation:Required
   233  	Key string `json:"key"`
   234  }
   235  
   236  type MappingLabelSpecifier_DestinationCluster struct {
   237  	// +kubebuilder:validation:Enum={"destination_cluster"}
   238  	// +kubebuilder:validation:Required
   239  	Key string `json:"key"`
   240  }
   241  
   242  type MappingLabelSpecifier_RequestHeaders struct {
   243  	// +kubebuilder:validation:Required
   244  	Key string `json:"key"`
   245  
   246  	// +kubebuilder:validation:Required
   247  	HeaderName string `json:"header_name"`
   248  
   249  	OmitIfNotPresent *bool `json:"omit_if_not_present,omitempty"`
   250  }
   251  
   252  type MappingLabelSpecifier_RemoteAddress struct {
   253  	// +kubebuilder:validation:Enum={"remote_address"}
   254  	// +kubebuilder:validation:Required
   255  	Key string `json:"key"`
   256  }
   257  
   258  type MappingLabelSpecifier_GenericKey struct {
   259  	// The default is "generic_key".
   260  	Key string `json:"key,omitempty"`
   261  
   262  	// +kubebuilder:validation:Required
   263  	Value string `json:"value"`
   264  
   265  	V2Shorthand bool `json:"v2Shorthand,omitempty"`
   266  }
   267  
   268  type AddedHeader struct {
   269  	Value  string `json:"value,omitempty"`
   270  	Append *bool  `json:"append,omitempty"`
   271  
   272  	// +kubebuilder:validation:Enum={"","string","null"}
   273  	V2Representation string `json:"v2Representation,omitempty"`
   274  }
   275  
   276  type KeepAlive struct {
   277  	Probes   *int `json:"probes,omitempty"`
   278  	IdleTime *int `json:"idle_time,omitempty"`
   279  	Interval *int `json:"interval,omitempty"`
   280  }
   281  
   282  type CORS struct {
   283  	// +k8s:conversion-gen=false
   284  	Origins        []string `json:"origins,omitempty"`
   285  	Methods        []string `json:"methods,omitempty"`
   286  	Headers        []string `json:"headers,omitempty"`
   287  	Credentials    *bool    `json:"credentials,omitempty"`
   288  	ExposedHeaders []string `json:"exposed_headers,omitempty"`
   289  	MaxAge         string   `json:"max_age,omitempty"`
   290  
   291  	V2CommaSeparatedOrigins bool `json:"v2CommaSeparatedOrigins,omitempty"`
   292  }
   293  
   294  type RetryPolicy struct {
   295  	// +kubebuilder:validation:Enum={"5xx","gateway-error","connect-failure","retriable-4xx","refused-stream","retriable-status-codes"}
   296  	RetryOn       string `json:"retry_on,omitempty"`
   297  	NumRetries    *int   `json:"num_retries,omitempty"`
   298  	PerTryTimeout string `json:"per_try_timeout,omitempty"`
   299  }
   300  
   301  type LoadBalancer struct {
   302  	// +kubebuilder:validation:Enum={"round_robin","ring_hash","maglev","least_request"}
   303  	// +kubebuilder:validation:Required
   304  	Policy   string              `json:"policy,omitempty"`
   305  	Cookie   *LoadBalancerCookie `json:"cookie,omitempty"`
   306  	Header   string              `json:"header,omitempty"`
   307  	SourceIp *bool               `json:"source_ip,omitempty"`
   308  }
   309  
   310  type LoadBalancerCookie struct {
   311  	// +kubebuilder:validation:Required
   312  	Name string `json:"name,omitempty"`
   313  	Path string `json:"path,omitempty"`
   314  	Ttl  string `json:"ttl,omitempty"`
   315  }
   316  
   317  // MappingStatus defines the observed state of Mapping
   318  type MappingStatus struct {
   319  	// +kubebuilder:validation:Enum={"","Inactive","Running"}
   320  	State string `json:"state,omitempty"`
   321  
   322  	Reason string `json:"reason,omitempty"`
   323  }
   324  
   325  // Mapping is the Schema for the mappings API
   326  //
   327  // +kubebuilder:object:root=true
   328  // +kubebuilder:subresource:status
   329  // +kubebuilder:printcolumn:name="Source Host",type=string,JSONPath=`.spec.host`
   330  // +kubebuilder:printcolumn:name="Source Prefix",type=string,JSONPath=`.spec.prefix`
   331  // +kubebuilder:printcolumn:name="Dest Service",type=string,JSONPath=`.spec.service`
   332  // +kubebuilder:printcolumn:name="State",type=string,JSONPath=`.status.state`
   333  // +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.reason`
   334  type Mapping struct {
   335  	metav1.TypeMeta   `json:""`
   336  	metav1.ObjectMeta `json:"metadata,omitempty"`
   337  
   338  	Spec   MappingSpec    `json:"spec,omitempty"`
   339  	Status *MappingStatus `json:"status,omitempty"`
   340  }
   341  
   342  // MappingList contains a list of Mappings.
   343  //
   344  // +kubebuilder:object:root=true
   345  type MappingList struct {
   346  	metav1.TypeMeta `json:""`
   347  	metav1.ListMeta `json:"metadata,omitempty"`
   348  	Items           []Mapping `json:"items"`
   349  }
   350  
   351  func init() {
   352  	SchemeBuilder.Register(&Mapping{}, &MappingList{})
   353  }
   354
View as plain text