Documentation
¶
Index ¶
- Constants
- Variables
- func ConfigToExecCluster(config *Config) (*clientauthenticationapi.Cluster, error)
- func DefaultKubernetesUserAgent() string
- func DefaultServerURL(host, apiPath string, groupVersion schema.GroupVersion, defaultTLS bool) (*url.URL, string, error)
- func DefaultServerUrlFor(config *Config) (*url.URL, string, error)
- func DefaultVersionedAPIPath(apiPath string, groupVersion schema.GroupVersion) string
- func HTTPClientFor(config *Config) (*http.Client, error)
- func HTTPWrappersForConfig(config *Config, rt http.RoundTripper) (http.RoundTripper, error)
- func IsConfigTransportTLS(config Config) bool
- func IsValidPathSegmentName(name string) []string
- func IsValidPathSegmentPrefix(name string) []string
- func LoadTLSFiles(c *Config) error
- func NewWarningWriter(out io.Writer, opts WarningWriterOptions) *warningWriter
- func RegisterAuthProviderPlugin(name string, plugin Factory) error
- func SetDefaultWarningHandler(l WarningHandler)
- func SetKubernetesDefaults(config *Config) error
- func TLSConfigFor(config *Config) (*tls.Config, error)
- func TransportFor(config *Config) (http.RoundTripper, error)
- func ValidatePathSegmentName(name string, prefix bool) []string
- type AuthProvider
- type AuthProviderConfigPersister
- type BackoffManager
- type ClientContentConfig
- type Config
- type ContentConfig
- type Factory
- type HTTPClient
- type ImpersonationConfig
- type Interface
- type IsRetryableErrorFunc
- type NoBackoff
- type NoWarnings
- type RESTClient
- func NewRESTClient(baseURL *url.URL, versionedAPIPath string, config ClientContentConfig, ...) (*RESTClient, error)
- func RESTClientFor(config *Config) (*RESTClient, error)
- func RESTClientForConfigAndClient(config *Config, httpClient *http.Client) (*RESTClient, error)
- func UnversionedRESTClientFor(config *Config) (*RESTClient, error)
- func UnversionedRESTClientForConfigAndClient(config *Config, httpClient *http.Client) (*RESTClient, error)
- func (c *RESTClient) APIVersion() schema.GroupVersion
- func (c *RESTClient) Delete() *Request
- func (c *RESTClient) Get() *Request
- func (c *RESTClient) GetRateLimiter() flowcontrol.RateLimiter
- func (c *RESTClient) Patch(pt types.PatchType) *Request
- func (c *RESTClient) Post() *Request
- func (c *RESTClient) Put() *Request
- func (c *RESTClient) Verb(verb string) *Request
- type Request
- func (r *Request) AbsPath(segments ...string) *Request
- func (r *Request) BackOff(manager BackoffManager) *Request
- func (r *Request) Body(obj interface{}) *Request
- func (r *Request) Do(ctx context.Context) Result
- func (r *Request) DoRaw(ctx context.Context) ([]byte, error)
- func (r *Request) Error() error
- func (r *Request) MaxRetries(maxRetries int) *Request
- func (r *Request) Name(resourceName string) *Request
- func (r *Request) Namespace(namespace string) *Request
- func (r *Request) NamespaceIfScoped(namespace string, scoped bool) *Request
- func (r *Request) Param(paramName, s string) *Request
- func (r *Request) Prefix(segments ...string) *Request
- func (r *Request) RequestURI(uri string) *Request
- func (r *Request) Resource(resource string) *Request
- func (r *Request) SetHeader(key string, values ...string) *Request
- func (r *Request) SpecificallyVersionedParams(obj runtime.Object, codec runtime.ParameterCodec, version schema.GroupVersion) *Request
- func (r *Request) Stream(ctx context.Context) (io.ReadCloser, error)
- func (r *Request) SubResource(subresources ...string) *Request
- func (r *Request) Suffix(segments ...string) *Request
- func (r *Request) Throttle(limiter flowcontrol.RateLimiter) *Request
- func (r *Request) Timeout(d time.Duration) *Request
- func (r *Request) URL() *url.URL
- func (r *Request) Verb(verb string) *Request
- func (r *Request) VersionedParams(obj runtime.Object, codec runtime.ParameterCodec) *Request
- func (r *Request) WarningHandler(handler WarningHandler) *Request
- func (r *Request) Watch(ctx context.Context) (watch.Interface, error)
- func (r *Request) WatchList(ctx context.Context) WatchListResult
- type RequestConstructionError
- type ResponseWrapper
- type Result
- func (r Result) ContentType(contentType *string) Result
- func (r Result) Error() error
- func (r Result) Get() (runtime.Object, error)
- func (r Result) Into(obj runtime.Object) error
- func (r Result) Raw() ([]byte, error)
- func (r Result) StatusCode(statusCode *int) Result
- func (r Result) Warnings() []net.WarningHeader
- func (r Result) WasCreated(wasCreated *bool) Result
- type RetryAfter
- type TLSClientConfig
- type URLBackoff
- type WarningHandler
- type WarningLogger
- type WarningWriterOptions
- type WatchListResult
- type WithRetry
Constants ¶
const ( DefaultQPS float32 = 5.0 DefaultBurst int = 10 )
Variables ¶
var ErrNotInCluster = errors.New("unable to load in-cluster configuration, KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT must be defined")
var NameMayNotBe = []string{".", ".."}
NameMayNotBe specifies strings that cannot be used as names specified as path segments (like the REST API or etcd store)
var NameMayNotContain = []string{"/", "%"}
NameMayNotContain specifies substrings that cannot be used in names specified as path segments (like the REST API or etcd store)
Functions ¶
func ConfigToExecCluster ¶ added in v0.20.0
func ConfigToExecCluster(config *Config) (*clientauthenticationapi.Cluster, error)
ConfigToExecCluster creates a clientauthenticationapi.Cluster with the corresponding fields from the provided Config.
func DefaultKubernetesUserAgent ¶
func DefaultKubernetesUserAgent() string
DefaultKubernetesUserAgent returns a User-Agent string built from static global vars.
func DefaultServerURL ¶
func DefaultServerURL(host, apiPath string, groupVersion schema.GroupVersion, defaultTLS bool) (*url.URL, string, error)
DefaultServerURL converts a host, host:port, or URL string to the default base server API path to use with a Client at a given API version following the standard conventions for a Kubernetes API.
func DefaultServerUrlFor ¶ added in v0.28.0
DefaultServerUrlFor is shared between IsConfigTransportTLS and RESTClientFor. It requires Host and Version to be set prior to being called.
func DefaultVersionedAPIPath ¶
func DefaultVersionedAPIPath(apiPath string, groupVersion schema.GroupVersion) string
DefaultVersionedAPIPathFor constructs the default path for the given group version, assuming the given API path, following the standard conventions of the Kubernetes API.
func HTTPClientFor ¶ added in v0.23.0
HTTPClientFor returns an http.Client that will provide the authentication or transport level security defined by the provided Config. Will return the default http.DefaultClient if no special case behavior is needed.
func HTTPWrappersForConfig ¶
func HTTPWrappersForConfig(config *Config, rt http.RoundTripper) (http.RoundTripper, error)
HTTPWrappersForConfig wraps a round tripper with any relevant layered behavior from the config. Exposed to allow more clients that need HTTP-like behavior but then must hijack the underlying connection (like WebSocket or HTTP2 clients). Pure HTTP clients should use the higher level TransportFor or RESTClientFor methods.
func IsConfigTransportTLS ¶
IsConfigTransportTLS returns true if and only if the provided config will result in a protected connection to the server when it is passed to restclient.RESTClientFor(). Use to determine when to send credentials over the wire.
Note: the Insecure flag is ignored when testing for this value, so MITM attacks are still possible.
func IsValidPathSegmentName ¶
IsValidPathSegmentName validates the name can be safely encoded as a path segment
func IsValidPathSegmentPrefix ¶
IsValidPathSegmentPrefix validates the name can be used as a prefix for a name which will be encoded as a path segment It does not check for exact matches with disallowed names, since an arbitrary suffix might make the name valid
func LoadTLSFiles ¶
LoadTLSFiles copies the data from the CertFile, KeyFile, and CAFile fields into the CertData, KeyData, and CAFile fields, or returns an error. If no error is returned, all three fields are either populated or were empty to start.
func NewWarningWriter ¶ added in v0.19.0
func NewWarningWriter(out io.Writer, opts WarningWriterOptions) *warningWriter
NewWarningWriter returns an implementation of WarningHandler that outputs code 299 warnings to the specified writer.
func SetDefaultWarningHandler ¶ added in v0.19.0
func SetDefaultWarningHandler(l WarningHandler)
SetDefaultWarningHandler sets the default handler clients use when warning headers are encountered. By default, warnings are logged. Several built-in implementations are provided:
- NoWarnings suppresses warnings.
- WarningLogger logs warnings.
- NewWarningWriter() outputs warnings to the provided writer.
func SetKubernetesDefaults ¶
SetKubernetesDefaults sets default values on the provided client config for accessing the Kubernetes API or returns an error if any of the defaults are impossible or invalid.
func TLSConfigFor ¶
TLSConfigFor returns a tls.Config that will provide the transport level security defined by the provided Config. Will return nil if no transport level security is requested.
func TransportFor ¶
func TransportFor(config *Config) (http.RoundTripper, error)
TransportFor returns an http.RoundTripper that will provide the authentication or transport level security defined by the provided Config. Will return the default http.DefaultTransport if no special case behavior is needed.
func ValidatePathSegmentName ¶
ValidatePathSegmentName validates the name can be safely encoded as a path segment
Types ¶
type AuthProvider ¶
type AuthProvider interface { // WrapTransport allows the plugin to create a modified RoundTripper that // attaches authorization headers (or other info) to requests. WrapTransport(http.RoundTripper) http.RoundTripper // Login allows the plugin to initialize its configuration. It must not // require direct user interaction. Login() error }
func GetAuthProvider ¶
func GetAuthProvider(clusterAddress string, apc *clientcmdapi.AuthProviderConfig, persister AuthProviderConfigPersister) (AuthProvider, error)
type AuthProviderConfigPersister ¶
AuthProviderConfigPersister allows a plugin to persist configuration info for just itself.
type BackoffManager ¶
type ClientContentConfig ¶ added in v0.17.0
type ClientContentConfig struct { // AcceptContentTypes specifies the types the client will accept and is optional. // If not set, ContentType will be used to define the Accept header AcceptContentTypes string // ContentType specifies the wire format used to communicate with the server. // This value will be set as the Accept header on requests made to the server if // AcceptContentTypes is not set, and as the default content type on any object // sent to the server. If not set, "application/json" is used. ContentType string // GroupVersion is the API version to talk to. Must be provided when initializing // a RESTClient directly. When initializing a Client, will be set with the default // code version. This is used as the default group version for VersionedParams. GroupVersion schema.GroupVersion // Negotiator is used for obtaining encoders and decoders for multiple // supported media types. Negotiator runtime.ClientNegotiator }
ClientContentConfig controls how RESTClient communicates with the server.
TODO: ContentConfig will be updated to accept a Negotiator instead of a NegotiatedSerializer and NegotiatedSerializer will be removed.
type Config ¶
type Config struct { // Host must be a host string, a host:port pair, or a URL to the base of the apiserver. // If a URL is given then the (optional) Path of that URL represents a prefix that must // be appended to all request URIs used to access the apiserver. This allows a frontend // proxy to easily relocate all of the apiserver endpoints. Host string // APIPath is a sub-path that points to an API root. APIPath string // ContentConfig contains settings that affect how objects are transformed when // sent to the server. ContentConfig // Server requires Basic authentication Username string Password string `datapolicy:"password"` // Server requires Bearer authentication. This client will not attempt to use // refresh tokens for an OAuth2 flow. // TODO: demonstrate an OAuth2 compatible client. BearerToken string `datapolicy:"token"` // Path to a file containing a BearerToken. // If set, the contents are periodically read. // The last successfully read value takes precedence over BearerToken. BearerTokenFile string // Impersonate is the configuration that RESTClient will use for impersonation. Impersonate ImpersonationConfig // Server requires plugin-specified authentication. AuthProvider *clientcmdapi.AuthProviderConfig // Callback to persist config for AuthProvider. AuthConfigPersister AuthProviderConfigPersister // Exec-based authentication provider. ExecProvider *clientcmdapi.ExecConfig // TLSClientConfig contains settings to enable transport layer security TLSClientConfig // UserAgent is an optional field that specifies the caller of this request. UserAgent string // DisableCompression bypasses automatic GZip compression requests to the // server. DisableCompression bool // Transport may be used for custom HTTP behavior. This attribute may not // be specified with the TLS client certificate options. Use WrapTransport // to provide additional per-server middleware behavior. Transport http.RoundTripper // WrapTransport will be invoked for custom HTTP behavior after the underlying // transport is initialized (either the transport created from TLSClientConfig, // Transport, or http.DefaultTransport). The config may layer other RoundTrippers // on top of the returned RoundTripper. // // A future release will change this field to an array. Use config.Wrap() // instead of setting this value directly. WrapTransport transport.WrapperFunc // QPS indicates the maximum QPS to the master from this client. // If it's zero, the created RESTClient will use DefaultQPS: 5 QPS float32 // Maximum burst for throttle. // If it's zero, the created RESTClient will use DefaultBurst: 10. Burst int // Rate limiter for limiting connections to the master from this client. If present overwrites QPS/Burst RateLimiter flowcontrol.RateLimiter // WarningHandler handles warnings in server responses. // If not set, the default warning handler is used. // See documentation for SetDefaultWarningHandler() for details. WarningHandler WarningHandler // The maximum length of time to wait before giving up on a server request. A value of zero means no timeout. Timeout time.Duration // Dial specifies the dial function for creating unencrypted TCP connections. Dial func(ctx context.Context, network, address string) (net.Conn, error) // Proxy is the proxy func to be used for all requests made by this // transport. If Proxy is nil, http.ProxyFromEnvironment is used. If Proxy // returns a nil *URL, no proxy is used. // // socks5 proxying does not currently support spdy streaming endpoints. Proxy func(*http.Request) (*url.URL, error) }
Config holds the common attributes that can be passed to a Kubernetes client on initialization.
func AddUserAgent ¶
func AnonymousClientConfig ¶
AnonymousClientConfig returns a copy of the given config with all user credentials (cert/key, bearer token, and username/password) and custom transports (WrapTransport, Transport) removed
func CopyConfig ¶
CopyConfig returns a copy of the given config
func ExecClusterToConfig ¶ added in v0.20.0
func ExecClusterToConfig(cluster *clientauthenticationapi.Cluster) (*Config, error)
ExecClusterToConfig creates a Config with the corresponding fields from the provided clientauthenticationapi.Cluster. The returned Config will be anonymous (i.e., it will not have any authentication-related fields set).
func InClusterConfig ¶
InClusterConfig returns a config object which uses the service account kubernetes gives to pods. It's intended for clients that expect to be running inside a pod running on kubernetes. It will return ErrNotInCluster if called from a process not running in a kubernetes environment.
func (*Config) GoString ¶
GoString implements fmt.GoStringer and sanitizes sensitive fields of Config to prevent accidental leaking via logs.
func (*Config) String ¶
String implements fmt.Stringer and sanitizes sensitive fields of Config to prevent accidental leaking via logs.
func (*Config) TransportConfig ¶
TransportConfig converts a client config to an appropriate transport config.
func (*Config) Wrap ¶
func (c *Config) Wrap(fn transport.WrapperFunc)
Wrap adds a transport middleware function that will give the caller an opportunity to wrap the underlying http.RoundTripper prior to the first API call being made. The provided function is invoked after any existing transport wrappers are invoked.
type ContentConfig ¶
type ContentConfig struct { // AcceptContentTypes specifies the types the client will accept and is optional. // If not set, ContentType will be used to define the Accept header AcceptContentTypes string // ContentType specifies the wire format used to communicate with the server. // This value will be set as the Accept header on requests made to the server, and // as the default content type on any object sent to the server. If not set, // "application/json" is used. ContentType string // GroupVersion is the API version to talk to. Must be provided when initializing // a RESTClient directly. When initializing a Client, will be set with the default // code version. GroupVersion *schema.GroupVersion // NegotiatedSerializer is used for obtaining encoders and decoders for multiple // supported media types. // // TODO: NegotiatedSerializer will be phased out as internal clients are removed // from Kubernetes. NegotiatedSerializer runtime.NegotiatedSerializer }
type Factory ¶
type Factory func(clusterAddress string, config map[string]string, persister AuthProviderConfigPersister) (AuthProvider, error)
Factory generates an AuthProvider plugin.
clusterAddress is the address of the current cluster. config is the initial configuration for this plugin. persister allows the plugin to save updated configuration.
type HTTPClient ¶
HTTPClient is an interface for testing a request object.
type ImpersonationConfig ¶
type ImpersonationConfig struct { // UserName is the username to impersonate on each request. UserName string // UID is a unique value that identifies the user. UID string // Groups are the groups to impersonate on each request. Groups []string // Extra is a free-form field which can be used to link some authentication information // to authorization information. This field allows you to impersonate it. Extra map[string][]string }
ImpersonationConfig has all the available impersonation options
type Interface ¶
type Interface interface { GetRateLimiter() flowcontrol.RateLimiter Verb(verb string) *Request Post() *Request Put() *Request Patch(pt types.PatchType) *Request Get() *Request Delete() *Request APIVersion() schema.GroupVersion }
Interface captures the set of operations for generically interacting with Kubernetes REST apis.
type IsRetryableErrorFunc ¶ added in v0.22.0
IsRetryableErrorFunc allows the client to provide its own function that determines whether the specified err from the server is retryable.
request: the original request sent to the server err: the server sent this error to us
The function returns true if the error is retryable and the request can be retried, otherwise it returns false. We have four mode of communications - 'Stream', 'Watch', 'Do' and 'DoRaw', this function allows us to customize the retryability aspect of each.
func (IsRetryableErrorFunc) IsErrorRetryable ¶ added in v0.22.0
func (r IsRetryableErrorFunc) IsErrorRetryable(request *http.Request, err error) bool
type NoBackoff ¶
type NoBackoff struct { }
NoBackoff is a stub implementation, can be used for mocking or else as a default.
func (*NoBackoff) CalculateBackoff ¶
type NoWarnings ¶ added in v0.19.0
type NoWarnings struct{}
NoWarnings is an implementation of WarningHandler that suppresses warnings.
func (NoWarnings) HandleWarningHeader ¶ added in v0.19.0
func (NoWarnings) HandleWarningHeader(code int, agent string, message string)
type RESTClient ¶
type RESTClient struct { // Set specific behavior of the client. If not set http.DefaultClient will be used. Client *http.Client // contains filtered or unexported fields }
RESTClient imposes common Kubernetes API conventions on a set of resource paths. The baseURL is expected to point to an HTTP or HTTPS path that is the parent of one or more resources. The server should return a decodable API resource object, or an api.Status object which contains information about the reason for any failure.
Most consumers should use client.New() to get a Kubernetes API client.
func NewRESTClient ¶
func NewRESTClient(baseURL *url.URL, versionedAPIPath string, config ClientContentConfig, rateLimiter flowcontrol.RateLimiter, client *http.Client) (*RESTClient, error)
NewRESTClient creates a new RESTClient. This client performs generic REST functions such as Get, Put, Post, and Delete on specified paths.
func RESTClientFor ¶
func RESTClientFor(config *Config) (*RESTClient, error)
RESTClientFor returns a RESTClient that satisfies the requested attributes on a client Config object. Note that a RESTClient may require fields that are optional when initializing a Client. A RESTClient created by this method is generic - it expects to operate on an API that follows the Kubernetes conventions, but may not be the Kubernetes API. RESTClientFor is equivalent to calling RESTClientForConfigAndClient(config, httpClient), where httpClient was generated with HTTPClientFor(config).
func RESTClientForConfigAndClient ¶ added in v0.23.0
func RESTClientForConfigAndClient(config *Config, httpClient *http.Client) (*RESTClient, error)
RESTClientForConfigAndClient returns a RESTClient that satisfies the requested attributes on a client Config object. Unlike RESTClientFor, RESTClientForConfigAndClient allows to pass an http.Client that is shared between all the API Groups and Versions. Note that the http client takes precedence over the transport values configured. The http client defaults to the `http.DefaultClient` if nil.
func UnversionedRESTClientFor ¶
func UnversionedRESTClientFor(config *Config) (*RESTClient, error)
UnversionedRESTClientFor is the same as RESTClientFor, except that it allows the config.Version to be empty.
func UnversionedRESTClientForConfigAndClient ¶ added in v0.23.0
func UnversionedRESTClientForConfigAndClient(config *Config, httpClient *http.Client) (*RESTClient, error)
UnversionedRESTClientForConfigAndClient is the same as RESTClientForConfigAndClient, except that it allows the config.Version to be empty.
func (*RESTClient) APIVersion ¶
func (c *RESTClient) APIVersion() schema.GroupVersion
APIVersion returns the APIVersion this RESTClient is expected to use.
func (*RESTClient) Delete ¶
func (c *RESTClient) Delete() *Request
Delete begins a DELETE request. Short for c.Verb("DELETE").
func (*RESTClient) Get ¶
func (c *RESTClient) Get() *Request
Get begins a GET request. Short for c.Verb("GET").
func (*RESTClient) GetRateLimiter ¶
func (c *RESTClient) GetRateLimiter() flowcontrol.RateLimiter
GetRateLimiter returns rate limiter for a given client, or nil if it's called on a nil client
func (*RESTClient) Patch ¶
func (c *RESTClient) Patch(pt types.PatchType) *Request
Patch begins a PATCH request. Short for c.Verb("Patch").
func (*RESTClient) Post ¶
func (c *RESTClient) Post() *Request
Post begins a POST request. Short for c.Verb("POST").
func (*RESTClient) Put ¶
func (c *RESTClient) Put() *Request
Put begins a PUT request. Short for c.Verb("PUT").
func (*RESTClient) Verb ¶
func (c *RESTClient) Verb(verb string) *Request
Verb begins a request with a verb (GET, POST, PUT, DELETE).
Example usage of RESTClient's request building interface: c, err := NewRESTClient(...) if err != nil { ... } resp, err := c.Verb("GET").
Path("pods"). SelectorParam("labels", "area=staging"). Timeout(10*time.Second). Do()
if err != nil { ... } list, ok := resp.(*api.PodList)
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request allows for building up a request to a server in a chained fashion. Any errors are stored until the end of your call, so you only have to check once.
func NewRequest ¶
func NewRequest(c *RESTClient) *Request
NewRequest creates a new request helper object for accessing runtime.Objects on a server.
func NewRequestWithClient ¶ added in v0.17.0
func NewRequestWithClient(base *url.URL, versionedAPIPath string, content ClientContentConfig, client *http.Client) *Request
NewRequestWithClient creates a Request with an embedded RESTClient for use in test scenarios.
func (*Request) AbsPath ¶
AbsPath overwrites an existing path with the segments provided. Trailing slashes are preserved when a single segment is passed.
func (*Request) BackOff ¶
func (r *Request) BackOff(manager BackoffManager) *Request
BackOff sets the request's backoff manager to the one specified, or defaults to the stub implementation if nil is provided
func (*Request) Body ¶
Body makes the request use obj as the body. Optional. If obj is a string, try to read a file of that name. If obj is a []byte, send it directly. If obj is an io.Reader, use it directly. If obj is a runtime.Object, marshal it correctly, and set Content-Type header. If obj is a runtime.Object and nil, do nothing. Otherwise, set an error.
func (*Request) Do ¶
Do formats and executes the request. Returns a Result object for easy response processing.
Error type:
- If the server responds with a status: *errors.StatusError or *errors.UnexpectedObjectError
- http.Client.Do errors are returned directly.
func (*Request) Error ¶ added in v0.27.0
Error returns any error encountered constructing the request, if any.
func (*Request) MaxRetries ¶ added in v0.19.0
MaxRetries makes the request use the given integer as a ceiling of retrying upon receiving "Retry-After" headers and 429 status-code in the response. The default is 10 unless this function is specifically called with a different value. A zero maxRetries prevent it from doing retires and return an error immediately.
func (*Request) Name ¶
Name sets the name of a resource to access (<resource>/[ns/<namespace>/]<name>)
func (*Request) Namespace ¶
Namespace applies the namespace scope to a request (<resource>/[ns/<namespace>/]<name>)
func (*Request) NamespaceIfScoped ¶
NamespaceIfScoped is a convenience function to set a namespace if scoped is true
func (*Request) Prefix ¶
Prefix adds segments to the relative beginning to the request path. These items will be placed before the optional Namespace, Resource, or Name sections. Setting AbsPath will clear any previously set Prefix segments
func (*Request) RequestURI ¶
RequestURI overwrites existing path and parameters with the value of the provided server relative URI.
func (*Request) Resource ¶
Resource sets the resource to access (<resource>/[ns/<namespace>/]<name>)
func (*Request) SpecificallyVersionedParams ¶
func (r *Request) SpecificallyVersionedParams(obj runtime.Object, codec runtime.ParameterCodec, version schema.GroupVersion) *Request
func (*Request) Stream ¶
Stream formats and executes the request, and offers streaming of the response. Returns io.ReadCloser which could be used for streaming of the response, or an error Any non-2xx http status code causes an error. If we get a non-2xx code, we try to convert the body into an APIStatus object. If we can, we return that as an error. Otherwise, we create an error that lists the http status and the content of the response.
func (*Request) SubResource ¶
SubResource sets a sub-resource path which can be multiple segments after the resource name but before the suffix.
func (*Request) Suffix ¶
Suffix appends segments to the end of the path. These items will be placed after the prefix and optional Namespace, Resource, or Name sections.
func (*Request) Throttle ¶
func (r *Request) Throttle(limiter flowcontrol.RateLimiter) *Request
Throttle receives a rate-limiter and sets or replaces an existing request limiter
func (*Request) Timeout ¶
Timeout makes the request use the given duration as an overall timeout for the request. Additionally, if set passes the value as "timeout" parameter in URL.
func (*Request) URL ¶
URL returns the current working URL. Check the result of Error() to ensure that the returned URL is valid.
func (*Request) VersionedParams ¶
VersionedParams will take the provided object, serialize it to a map[string][]string using the implicit RESTClient API version and the default parameter codec, and then add those as parameters to the request. Use this to provide versioned query parameters from client libraries. VersionedParams will not write query parameters that have omitempty set and are empty. If a parameter has already been set it is appended to (Params and VersionedParams are additive).
func (*Request) WarningHandler ¶ added in v0.19.0
func (r *Request) WarningHandler(handler WarningHandler) *Request
WarningHandler sets the handler this client uses when warning headers are encountered. If set to nil, this client will use the default warning handler (see SetDefaultWarningHandler).
func (*Request) Watch ¶
Watch attempts to begin watching the requested location. Returns a watch.Interface, or an error.
func (*Request) WatchList ¶ added in v0.31.0
func (r *Request) WatchList(ctx context.Context) WatchListResult
WatchList establishes a stream to get a consistent snapshot of data from the server as described in https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/3157-watch-list#proposal
Note that the watchlist requires properly setting the ListOptions otherwise it just establishes a regular watch with the server. Check the documentation https://kubernetes.io/docs/reference/using-api/api-concepts/#streaming-lists to see what parameters are currently required.
type RequestConstructionError ¶
type RequestConstructionError struct {
Err error
}
RequestConstructionError is returned when there's an error assembling a request.
func (*RequestConstructionError) Error ¶
func (r *RequestConstructionError) Error() string
Error returns a textual description of 'r'.
type ResponseWrapper ¶
type ResponseWrapper interface { DoRaw(context.Context) ([]byte, error) Stream(context.Context) (io.ReadCloser, error) }
ResponseWrapper is an interface for getting a response. The response may be either accessed as a raw data (the whole output is put into memory) or as a stream.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result contains the result of calling Request.Do().
func (Result) ContentType ¶ added in v0.26.0
ContentType returns the "Content-Type" response header into the passed string, returning the Result for possible chaining. (Only valid if no error code was returned.)
func (Result) Error ¶
Error returns the error executing the request, nil if no error occurred. If the returned object is of type Status and has Status != StatusSuccess, the additional information in Status will be used to enrich the error. See the Request.Do() comment for what errors you might get.
func (Result) Get ¶
Get returns the result as an object, which means it passes through the decoder. If the returned object is of type Status and has .Status != StatusSuccess, the additional information in Status will be used to enrich the error.
func (Result) Into ¶
Into stores the result into obj, if possible. If obj is nil it is ignored. If the returned object is of type Status and has .Status != StatusSuccess, the additional information in Status will be used to enrich the error.
func (Result) StatusCode ¶
StatusCode returns the HTTP status code of the request. (Only valid if no error was returned.)
func (Result) Warnings ¶ added in v0.19.0
func (r Result) Warnings() []net.WarningHeader
Warnings returns any warning headers received in the response
func (Result) WasCreated ¶
WasCreated updates the provided bool pointer to whether the server returned 201 created or a different response.
type RetryAfter ¶ added in v0.22.0
type RetryAfter struct { // Wait is the duration the server has asked us to wait before // the next retry is initiated. // This is the value of the 'Retry-After' response header in seconds. Wait time.Duration // Attempt is the Nth attempt after which we have received a retryable // error or a 'Retry-After' response header from the server. Attempt int // Reason describes why we are retrying the request Reason string }
RetryAfter holds information associated with the next retry.
type TLSClientConfig ¶
type TLSClientConfig struct { // Server should be accessed without verifying the TLS certificate. For testing only. Insecure bool // ServerName is passed to the server for SNI and is used in the client to check server // certificates against. If ServerName is empty, the hostname used to contact the // server is used. ServerName string // Server requires TLS client certificate authentication CertFile string // Server requires TLS client certificate authentication KeyFile string // Trusted root certificates for server CAFile string // CertData holds PEM-encoded bytes (typically read from a client certificate file). // CertData takes precedence over CertFile CertData []byte // KeyData holds PEM-encoded bytes (typically read from a client certificate key file). // KeyData takes precedence over KeyFile KeyData []byte `datapolicy:"security-key"` // CAData holds PEM-encoded bytes (typically read from a root certificates bundle). // CAData takes precedence over CAFile CAData []byte // NextProtos is a list of supported application level protocols, in order of preference. // Used to populate tls.Config.NextProtos. // To indicate to the server http/1.1 is preferred over http/2, set to ["http/1.1", "h2"] (though the server is free to ignore that preference). // To use only http/1.1, set to ["http/1.1"]. NextProtos []string }
+k8s:deepcopy-gen=true TLSClientConfig contains settings to enable transport layer security
func (*TLSClientConfig) DeepCopy ¶
func (in *TLSClientConfig) DeepCopy() *TLSClientConfig
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TLSClientConfig.
func (*TLSClientConfig) DeepCopyInto ¶
func (in *TLSClientConfig) DeepCopyInto(out *TLSClientConfig)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (TLSClientConfig) GoString ¶
func (c TLSClientConfig) GoString() string
GoString implements fmt.GoStringer and sanitizes sensitive fields of TLSClientConfig to prevent accidental leaking via logs.
func (TLSClientConfig) String ¶
func (c TLSClientConfig) String() string
String implements fmt.Stringer and sanitizes sensitive fields of TLSClientConfig to prevent accidental leaking via logs.
type URLBackoff ¶
type URLBackoff struct { // Uses backoff as underlying implementation. Backoff *flowcontrol.Backoff }
URLBackoff struct implements the semantics on top of Backoff which we need for URL specific exponential backoff.
func (*URLBackoff) CalculateBackoff ¶
func (b *URLBackoff) CalculateBackoff(actualUrl *url.URL) time.Duration
CalculateBackoff takes a url and back's off exponentially, based on its knowledge of existing failures.
func (*URLBackoff) Disable ¶
func (b *URLBackoff) Disable()
Disable makes the backoff trivial, i.e., sets it to zero. This might be used by tests which want to run 1000s of mock requests without slowing down.
func (*URLBackoff) Sleep ¶
func (b *URLBackoff) Sleep(d time.Duration)
func (*URLBackoff) UpdateBackoff ¶
func (b *URLBackoff) UpdateBackoff(actualUrl *url.URL, err error, responseCode int)
UpdateBackoff updates backoff metadata
type WarningHandler ¶ added in v0.19.0
type WarningHandler interface { // HandleWarningHeader is called with the warn code, agent, and text when a warning header is countered. HandleWarningHeader(code int, agent string, text string) }
WarningHandler is an interface for handling warning headers
type WarningLogger ¶ added in v0.19.0
type WarningLogger struct{}
WarningLogger is an implementation of WarningHandler that logs code 299 warnings
func (WarningLogger) HandleWarningHeader ¶ added in v0.19.0
func (WarningLogger) HandleWarningHeader(code int, agent string, message string)
type WarningWriterOptions ¶ added in v0.19.0
type WarningWriterOptions struct { // Deduplicate indicates a given warning message should only be written once. // Setting this to true in a long-running process handling many warnings can result in increased memory use. Deduplicate bool // Color indicates that warning output can include ANSI color codes Color bool }
WarningWriterOptions controls the behavior of a WarningHandler constructed using NewWarningWriter()
type WatchListResult ¶ added in v0.31.0
type WatchListResult struct {
// contains filtered or unexported fields
}
type WithRetry ¶ added in v0.22.0
type WithRetry interface { // IsNextRetry advances the retry counter appropriately // and returns true if the request should be retried, // otherwise it returns false, if: // - we have already reached the maximum retry threshold. // - the error does not fall into the retryable category. // - the server has not sent us a 429, or 5xx status code and the // 'Retry-After' response header is not set with a value. // - we need to seek to the beginning of the request body before we // initiate the next retry, the function should log an error and // return false if it fails to do so. // // restReq: the associated rest.Request // httpReq: the HTTP Request sent to the server // resp: the response sent from the server, it is set if err is nil // err: the server sent this error to us, if err is set then resp is nil. // f: a IsRetryableErrorFunc function provided by the client that determines // if the err sent by the server is retryable. IsNextRetry(ctx context.Context, restReq *Request, httpReq *http.Request, resp *http.Response, err error, f IsRetryableErrorFunc) bool // Before should be invoked prior to each attempt, including // the first one. If an error is returned, the request should // be aborted immediately. // // Before may also be additionally responsible for preparing // the request for the next retry, namely in terms of resetting // the request body in case it has been read. Before(ctx context.Context, r *Request) error // After should be invoked immediately after an attempt is made. After(ctx context.Context, r *Request, resp *http.Response, err error) // WrapPreviousError wraps the error from any previous attempt into // the final error specified in 'finalErr', so the user has more // context why the request failed. // For example, if a request times out after multiple retries then // we see a generic context.Canceled or context.DeadlineExceeded // error which is not very useful in debugging. This function can // wrap any error from previous attempt(s) to provide more context to // the user. The error returned in 'err' must satisfy the // following conditions: // a: errors.Unwrap(err) = errors.Unwrap(finalErr) if finalErr // implements Unwrap // b: errors.Unwrap(err) = finalErr if finalErr does not // implements Unwrap // c: errors.Is(err, otherErr) = errors.Is(finalErr, otherErr) WrapPreviousError(finalErr error) (err error) }
WithRetry allows the client to retry a request up to a certain number of times Note that WithRetry is not safe for concurrent use by multiple goroutines without additional locking or coordination.