1 /* 2 Copyright 2014 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package rest 18 19 import ( 20 "net/http" 21 "net/url" 22 "os" 23 "strconv" 24 "strings" 25 "time" 26 27 "k8s.io/apimachinery/pkg/runtime" 28 "k8s.io/apimachinery/pkg/runtime/schema" 29 "k8s.io/apimachinery/pkg/types" 30 "k8s.io/client-go/util/flowcontrol" 31 ) 32 33 const ( 34 // Environment variables: Note that the duration should be long enough that the backoff 35 // persists for some reasonable time (i.e. 120 seconds). The typical base might be "1". 36 envBackoffBase = "KUBE_CLIENT_BACKOFF_BASE" 37 envBackoffDuration = "KUBE_CLIENT_BACKOFF_DURATION" 38 ) 39 40 // Interface captures the set of operations for generically interacting with Kubernetes REST apis. 41 type Interface interface { 42 GetRateLimiter() flowcontrol.RateLimiter 43 Verb(verb string) *Request 44 Post() *Request 45 Put() *Request 46 Patch(pt types.PatchType) *Request 47 Get() *Request 48 Delete() *Request 49 APIVersion() schema.GroupVersion 50 } 51 52 // ClientContentConfig controls how RESTClient communicates with the server. 53 // 54 // TODO: ContentConfig will be updated to accept a Negotiator instead of a 55 // NegotiatedSerializer and NegotiatedSerializer will be removed. 56 type ClientContentConfig struct { 57 // AcceptContentTypes specifies the types the client will accept and is optional. 58 // If not set, ContentType will be used to define the Accept header 59 AcceptContentTypes string 60 // ContentType specifies the wire format used to communicate with the server. 61 // This value will be set as the Accept header on requests made to the server if 62 // AcceptContentTypes is not set, and as the default content type on any object 63 // sent to the server. If not set, "application/json" is used. 64 ContentType string 65 // GroupVersion is the API version to talk to. Must be provided when initializing 66 // a RESTClient directly. When initializing a Client, will be set with the default 67 // code version. This is used as the default group version for VersionedParams. 68 GroupVersion schema.GroupVersion 69 // Negotiator is used for obtaining encoders and decoders for multiple 70 // supported media types. 71 Negotiator runtime.ClientNegotiator 72 } 73 74 // RESTClient imposes common Kubernetes API conventions on a set of resource paths. 75 // The baseURL is expected to point to an HTTP or HTTPS path that is the parent 76 // of one or more resources. The server should return a decodable API resource 77 // object, or an api.Status object which contains information about the reason for 78 // any failure. 79 // 80 // Most consumers should use client.New() to get a Kubernetes API client. 81 type RESTClient struct { 82 // base is the root URL for all invocations of the client 83 base *url.URL 84 // versionedAPIPath is a path segment connecting the base URL to the resource root 85 versionedAPIPath string 86 87 // content describes how a RESTClient encodes and decodes responses. 88 content ClientContentConfig 89 90 // creates BackoffManager that is passed to requests. 91 createBackoffMgr func() BackoffManager 92 93 // rateLimiter is shared among all requests created by this client unless specifically 94 // overridden. 95 rateLimiter flowcontrol.RateLimiter 96 97 // warningHandler is shared among all requests created by this client. 98 // If not set, defaultWarningHandler is used. 99 warningHandler WarningHandler 100 101 // Set specific behavior of the client. If not set http.DefaultClient will be used. 102 Client *http.Client 103 } 104 105 // NewRESTClient creates a new RESTClient. This client performs generic REST functions 106 // such as Get, Put, Post, and Delete on specified paths. 107 func NewRESTClient(baseURL *url.URL, versionedAPIPath string, config ClientContentConfig, rateLimiter flowcontrol.RateLimiter, client *http.Client) (*RESTClient, error) { 108 if len(config.ContentType) == 0 { 109 config.ContentType = "application/json" 110 } 111 112 base := *baseURL 113 if !strings.HasSuffix(base.Path, "/") { 114 base.Path += "/" 115 } 116 base.RawQuery = "" 117 base.Fragment = "" 118 119 return &RESTClient{ 120 base: &base, 121 versionedAPIPath: versionedAPIPath, 122 content: config, 123 createBackoffMgr: readExpBackoffConfig, 124 rateLimiter: rateLimiter, 125 126 Client: client, 127 }, nil 128 } 129 130 // GetRateLimiter returns rate limiter for a given client, or nil if it's called on a nil client 131 func (c *RESTClient) GetRateLimiter() flowcontrol.RateLimiter { 132 if c == nil { 133 return nil 134 } 135 return c.rateLimiter 136 } 137 138 // readExpBackoffConfig handles the internal logic of determining what the 139 // backoff policy is. By default if no information is available, NoBackoff. 140 // TODO Generalize this see #17727 . 141 func readExpBackoffConfig() BackoffManager { 142 backoffBase := os.Getenv(envBackoffBase) 143 backoffDuration := os.Getenv(envBackoffDuration) 144 145 backoffBaseInt, errBase := strconv.ParseInt(backoffBase, 10, 64) 146 backoffDurationInt, errDuration := strconv.ParseInt(backoffDuration, 10, 64) 147 if errBase != nil || errDuration != nil { 148 return &NoBackoff{} 149 } 150 return &URLBackoff{ 151 Backoff: flowcontrol.NewBackOff( 152 time.Duration(backoffBaseInt)*time.Second, 153 time.Duration(backoffDurationInt)*time.Second)} 154 } 155 156 // Verb begins a request with a verb (GET, POST, PUT, DELETE). 157 // 158 // Example usage of RESTClient's request building interface: 159 // c, err := NewRESTClient(...) 160 // if err != nil { ... } 161 // resp, err := c.Verb("GET"). 162 // 163 // Path("pods"). 164 // SelectorParam("labels", "area=staging"). 165 // Timeout(10*time.Second). 166 // Do() 167 // 168 // if err != nil { ... } 169 // list, ok := resp.(*api.PodList) 170 func (c *RESTClient) Verb(verb string) *Request { 171 return NewRequest(c).Verb(verb) 172 } 173 174 // Post begins a POST request. Short for c.Verb("POST"). 175 func (c *RESTClient) Post() *Request { 176 return c.Verb("POST") 177 } 178 179 // Put begins a PUT request. Short for c.Verb("PUT"). 180 func (c *RESTClient) Put() *Request { 181 return c.Verb("PUT") 182 } 183 184 // Patch begins a PATCH request. Short for c.Verb("Patch"). 185 func (c *RESTClient) Patch(pt types.PatchType) *Request { 186 return c.Verb("PATCH").SetHeader("Content-Type", string(pt)) 187 } 188 189 // Get begins a GET request. Short for c.Verb("GET"). 190 func (c *RESTClient) Get() *Request { 191 return c.Verb("GET") 192 } 193 194 // Delete begins a DELETE request. Short for c.Verb("DELETE"). 195 func (c *RESTClient) Delete() *Request { 196 return c.Verb("DELETE") 197 } 198 199 // APIVersion returns the APIVersion this RESTClient is expected to use. 200 func (c *RESTClient) APIVersion() schema.GroupVersion { 201 return c.content.GroupVersion 202 } 203