crd_mapping.go

Documentation: github.com/emissary-ingress/emissary/v3/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  	// +kubebuilder:validation:MinItems=1
    83  	HealthChecks []HealthCheck `json:"health_checks,omitempty"`
    84  
    85  	// use_websocket is deprecated, and is equivlaent to setting
    86  	// `allow_upgrade: ["websocket"]`
    87  	//
    88  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.DeprecatedUseWebsocket.
    89  	DeprecatedUseWebsocket *bool `json:"use_websocket,omitempty"`
    90  
    91  	// A case-insensitive list of the non-HTTP protocols to allow
    92  	// "upgrading" to from HTTP via the "Connection: upgrade"
    93  	// mechanism[1].  After the upgrade, Ambassador does not
    94  	// interpret the traffic, and behaves similarly to how it does
    95  	// for TCPMappings.
    96  	//
    97  	// [1]: https://tools.ietf.org/html/rfc7230#section-6.7
    98  	//
    99  	// For example, if your upstream service supports WebSockets,
   100  	// you would write
   101  	//
   102  	//    allow_upgrade:
   103  	//    - websocket
   104  	//
   105  	// Or if your upstream service supports upgrading from HTTP to
   106  	// SPDY (as the Kubernetes apiserver does for `kubectl exec`
   107  	// functionality), you would write
   108  	//
   109  	//    allow_upgrade:
   110  	//    - spdy/3.1
   111  	AllowUpgrade []string `json:"allow_upgrade,omitempty"`
   112  
   113  	Weight                *int              `json:"weight,omitempty"`
   114  	BypassAuth            *bool             `json:"bypass_auth,omitempty"`
   115  	AuthContextExtensions map[string]string `json:"auth_context_extensions,omitempty"`
   116  	// If true, bypasses any `error_response_overrides` set on the Ambassador module.
   117  	BypassErrorResponseOverrides *bool `json:"bypass_error_response_overrides,omitempty"`
   118  	// Error response overrides for this Mapping. Replaces all of the `error_response_overrides`
   119  	// set on the Ambassador module, if any.
   120  	// +kubebuilder:validation:MinItems=1
   121  	ErrorResponseOverrides []ErrorResponseOverride `json:"error_response_overrides,omitempty"`
   122  	Modules                []UntypedDict           `json:"modules,omitempty"`
   123  
   124  	// Exact match for the hostname of a request if HostRegex is false; regex match for the
   125  	// hostname if HostRegex is true.
   126  	//
   127  	// Host specifies both a match for the ':authority' header of a request, as well as a match
   128  	// criterion for Host CRDs: a Mapping that specifies Host will not associate with a Host that
   129  	// doesn't have a matching Hostname.
   130  	//
   131  	// If both Host and Hostname are set, an error is logged, Host is ignored, and Hostname is
   132  	// used.
   133  	//
   134  	// DEPRECATED: Host is either an exact match or a regex, depending on HostRegex. Use HostName instead.
   135  	//
   136  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.host and MappingSpec.host_regex in
   137  	// favor of a MappingSpec.deprecated_hostname_regex.
   138  	DeprecatedHost string `json:"host,omitempty"`
   139  	// DEPRECATED: Host is either an exact match or a regex, depending on HostRegex. Use HostName instead.
   140  	//
   141  	// TODO(lukeshu): In v3alpha2, get rid of MappingSpec.host and MappingSpec.host_regex in
   142  	// favor of a MappingSpec.deprecated_hostname_regex.
   143  	DeprecatedHostRegex *bool `json:"host_regex,omitempty"`
   144  	// Hostname is a DNS glob specifying the hosts to which this Mapping applies.
   145  	//
   146  	// Hostname specifies both a match for the ':authority' header of a request, as well as a
   147  	// match criterion for Host CRDs: a Mapping that specifies Hostname will not associate with
   148  	// a Host that doesn't have a matching Hostname.
   149  	//
   150  	// If both Host and Hostname are set, an error is logged, Host is ignored, and Hostname is
   151  	// used.
   152  	Hostname string `json:"hostname,omitempty"`
   153  
   154  	Headers              map[string]string `json:"headers,omitempty"`
   155  	RegexHeaders         map[string]string `json:"regex_headers,omitempty"`
   156  	Labels               DomainMap         `json:"labels,omitempty"`
   157  	EnvoyOverride        *UntypedDict      `json:"envoy_override,omitempty"`
   158  	LoadBalancer         *LoadBalancer     `json:"load_balancer,omitempty"`
   159  	QueryParameters      map[string]string `json:"query_parameters,omitempty"`
   160  	RegexQueryParameters map[string]string `json:"regex_query_parameters,omitempty"`
   161  	StatsName            string            `json:"stats_name,omitempty"`
   162  
   163  	V2ExplicitTLS         *V2ExplicitTLS `json:"v2ExplicitTLS,omitempty"`
   164  	V2BoolHeaders         []string       `json:"v2BoolHeaders,omitempty"`
   165  	V2BoolQueryParameters []string       `json:"v2BoolQueryParameters,omitempty"`
   166  }
   167  
   168  type RegexMap struct {
   169  	Pattern      string `json:"pattern,omitempty"`
   170  	Substitution string `json:"substitution,omitempty"`
   171  }
   172  
   173  // DocsInfo provides some extra information about the docs for the Mapping.
   174  // Docs is used by both the agent and the DevPortal.
   175  type DocsInfo struct {
   176  	Path        string               `json:"path,omitempty"`
   177  	URL         string               `json:"url,omitempty"`
   178  	Ignored     *bool                `json:"ignored,omitempty"`
   179  	DisplayName string               `json:"display_name,omitempty"`
   180  	Timeout     *MillisecondDuration `json:"timeout_ms,omitempty"`
   181  }
   182  
   183  // These are separate types partly because it makes it easier to think about
   184  // how `DomainMap` is built up, but also because it's pretty awful to read
   185  // a type definition that's four or five levels deep with maps and arrays.
   186  
   187  // A DomainMap is the overall Mapping.spec.Labels type. It maps domains (kind of
   188  // like namespaces for Mapping labels) to arrays of label groups.
   189  type DomainMap map[string]MappingLabelGroupsArray
   190  
   191  // A MappingLabelGroupsArray is an array of MappingLabelGroups. I know, complex.
   192  type MappingLabelGroupsArray []MappingLabelGroup
   193  
   194  // A MappingLabelGroup is a single element of a MappingLabelGroupsArray: a second
   195  // map, where the key is a human-readable name that identifies the group.
   196  //
   197  // +kubebuilder:validation:MinProperties=1
   198  // +kubebuilder:validation:MaxProperties=1
   199  type MappingLabelGroup map[string]MappingLabelsArray
   200  
   201  // A MappingLabelsArray is the value in the MappingLabelGroup: an array of label
   202  // specifiers.
   203  type MappingLabelsArray []MappingLabelSpecifier
   204  
   205  // A MappingLabelSpecifier (finally!) defines a single label.
   206  //
   207  // This mimics envoy/config/route/v3/route_components.proto:RateLimit:Action:action_specifier.
   208  //
   209  // +kubebuilder:validation:MinProperties=1
   210  // +kubebuilder:validation:MaxProperties=1
   211  type MappingLabelSpecifier struct {
   212  	// Sets the label "source_cluster=«Envoy source cluster name»".
   213  	SourceCluster *MappingLabelSpecifier_SourceCluster `json:"source_cluster,omitempty"`
   214  
   215  	// Sets the label "destination_cluster=«Envoy destination cluster name»".
   216  	DestinationCluster *MappingLabelSpecifier_DestinationCluster `json:"destination_cluster,omitempty"`
   217  
   218  	// If the «header_name» header is set, then set the label "«key»=«Value of the
   219  	// «header_name» header»"; otherwise skip applying this label group.
   220  	RequestHeaders *MappingLabelSpecifier_RequestHeaders `json:"request_headers,omitempty"`
   221  
   222  	// Sets the label "remote_address=«IP address of the client»".
   223  	RemoteAddress *MappingLabelSpecifier_RemoteAddress `json:"remote_address,omitempty"`
   224  
   225  	// Sets the label "«key»=«value»" (where by default «key»
   226  	// is "generic_key").
   227  	GenericKey *MappingLabelSpecifier_GenericKey `json:"generic_key,omitempty"`
   228  
   229  	// TODO: Consider implementing `header_value_match`, `metadata`, or `extension`?
   230  }
   231  
   232  type MappingLabelSpecifier_SourceCluster struct {
   233  	// +kubebuilder:validation:Enum={"source_cluster"}
   234  	// +kubebuilder:validation:Required
   235  	Key string `json:"key"`
   236  }
   237  
   238  type MappingLabelSpecifier_DestinationCluster struct {
   239  	// +kubebuilder:validation:Enum={"destination_cluster"}
   240  	// +kubebuilder:validation:Required
   241  	Key string `json:"key"`
   242  }
   243  
   244  type MappingLabelSpecifier_RequestHeaders struct {
   245  	// +kubebuilder:validation:Required
   246  	Key string `json:"key"`
   247  
   248  	// +kubebuilder:validation:Required
   249  	HeaderName string `json:"header_name"`
   250  
   251  	OmitIfNotPresent *bool `json:"omit_if_not_present,omitempty"`
   252  }
   253  
   254  type MappingLabelSpecifier_RemoteAddress struct {
   255  	// +kubebuilder:validation:Enum={"remote_address"}
   256  	// +kubebuilder:validation:Required
   257  	Key string `json:"key"`
   258  }
   259  
   260  type MappingLabelSpecifier_GenericKey struct {
   261  	// The default is "generic_key".
   262  	Key string `json:"key,omitempty"`
   263  
   264  	// +kubebuilder:validation:Required
   265  	Value string `json:"value"`
   266  
   267  	V2Shorthand bool `json:"v2Shorthand,omitempty"`
   268  }
   269  
   270  type AddedHeader struct {
   271  	Value  string `json:"value,omitempty"`
   272  	Append *bool  `json:"append,omitempty"`
   273  
   274  	// +kubebuilder:validation:Enum={"","string","null"}
   275  	V2Representation string `json:"v2Representation,omitempty"`
   276  }
   277  
   278  type KeepAlive struct {
   279  	Probes   *int `json:"probes,omitempty"`
   280  	IdleTime *int `json:"idle_time,omitempty"`
   281  	Interval *int `json:"interval,omitempty"`
   282  }
   283  
   284  type CORS struct {
   285  	// +k8s:conversion-gen=false
   286  	Origins        []string `json:"origins,omitempty"`
   287  	Methods        []string `json:"methods,omitempty"`
   288  	Headers        []string `json:"headers,omitempty"`
   289  	Credentials    *bool    `json:"credentials,omitempty"`
   290  	ExposedHeaders []string `json:"exposed_headers,omitempty"`
   291  	MaxAge         string   `json:"max_age,omitempty"`
   292  
   293  	V2CommaSeparatedOrigins bool `json:"v2CommaSeparatedOrigins,omitempty"`
   294  }
   295  
   296  type RetryPolicy struct {
   297  	// +kubebuilder:validation:Enum={"5xx","gateway-error","connect-failure","retriable-4xx","refused-stream","retriable-status-codes"}
   298  	RetryOn       string `json:"retry_on,omitempty"`
   299  	NumRetries    *int   `json:"num_retries,omitempty"`
   300  	PerTryTimeout string `json:"per_try_timeout,omitempty"`
   301  }
   302  
   303  type LoadBalancer struct {
   304  	// +kubebuilder:validation:Enum={"round_robin","ring_hash","maglev","least_request"}
   305  	// +kubebuilder:validation:Required
   306  	Policy   string              `json:"policy,omitempty"`
   307  	Cookie   *LoadBalancerCookie `json:"cookie,omitempty"`
   308  	Header   string              `json:"header,omitempty"`
   309  	SourceIp *bool               `json:"source_ip,omitempty"`
   310  }
   311  
   312  type LoadBalancerCookie struct {
   313  	// +kubebuilder:validation:Required
   314  	Name string `json:"name,omitempty"`
   315  	Path string `json:"path,omitempty"`
   316  	Ttl  string `json:"ttl,omitempty"`
   317  }
   318  
   319  // MappingStatus defines the observed state of Mapping
   320  type MappingStatus struct {
   321  	// +kubebuilder:validation:Enum={"","Inactive","Running"}
   322  	State string `json:"state,omitempty"`
   323  
   324  	Reason string `json:"reason,omitempty"`
   325  }
   326  
   327  // Mapping is the Schema for the mappings API
   328  //
   329  // +kubebuilder:object:root=true
   330  // +kubebuilder:subresource:status
   331  // +kubebuilder:printcolumn:name="Source Host",type=string,JSONPath=`.spec.host`
   332  // +kubebuilder:printcolumn:name="Source Prefix",type=string,JSONPath=`.spec.prefix`
   333  // +kubebuilder:printcolumn:name="Dest Service",type=string,JSONPath=`.spec.service`
   334  // +kubebuilder:printcolumn:name="State",type=string,JSONPath=`.status.state`
   335  // +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.reason`
   336  type Mapping struct {
   337  	metav1.TypeMeta   `json:""`
   338  	metav1.ObjectMeta `json:"metadata,omitempty"`
   339  
   340  	Spec   MappingSpec    `json:"spec,omitempty"`
   341  	Status *MappingStatus `json:"status,omitempty"`
   342  }
   343  
   344  // MappingList contains a list of Mappings.
   345  //
   346  // +kubebuilder:object:root=true
   347  type MappingList struct {
   348  	metav1.TypeMeta `json:""`
   349  	metav1.ListMeta `json:"metadata,omitempty"`
   350  	Items           []Mapping `json:"items"`
   351  }
   352  
   353  func init() {
   354  	SchemeBuilder.Register(&Mapping{}, &MappingList{})
   355  }
   356
View as plain text