From 777e085a97882b134cf99139c5ab18b0dd15075c Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Sat, 19 Jan 2019 05:49:49 -0500 Subject: [PATCH] Update swagger/openapi descriptions (#12279) --- .../en/docs/concepts/overview/kubernetes-api.md | 15 ++++++++++----- .../en/docs/reference/access-authn-authz/abac.md | 7 +++---- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index 5e5f2122aa..179b471dcd 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -33,17 +33,19 @@ What constitutes a compatible change and how to change the API are detailed by t ## OpenAPI and Swagger definitions -Complete API details are documented using [Swagger v1.2](http://swagger.io/) and [OpenAPI](https://www.openapis.org/). The Kubernetes apiserver (aka "master") exposes an API that can be used to retrieve the Swagger v1.2 Kubernetes API spec located at `/swaggerapi`. +Complete API details are documented using [OpenAPI](https://www.openapis.org/). -Starting with Kubernetes 1.10, OpenAPI spec is served in a single `/openapi/v2` endpoint. The format-separated endpoints (`/swagger.json`, `/swagger-2.0.0.json`, `/swagger-2.0.0.pb-v1`, `/swagger-2.0.0.pb-v1.gz`) are deprecated and will get removed in Kubernetes 1.14. - -Requested format is specified by setting HTTP headers: +Starting with Kubernetes 1.10, the Kubernetes API server serves an OpenAPI spec via the `/openapi/v2` endpoint. +The requested format is specified by setting HTTP headers: Header | Possible Values ------ | --------------- Accept | `application/json`, `application/com.github.proto-openapi.spec.v2@v1.0+protobuf` (the default content-type is `application/json` for `*/*` or not passing this header) Accept-Encoding | `gzip` (not passing this header is acceptable) +Prior to 1.14, format-separated endpoints (`/swagger.json`, `/swagger-2.0.0.json`, `/swagger-2.0.0.pb-v1`, `/swagger-2.0.0.pb-v1.gz`) +serve the OpenAPI spec in different formats. These endpoints are deprecated, and will be removed in Kubernetes 1.14. + **Examples of getting OpenAPI spec**: Before 1.10 | Starting with Kubernetes 1.10 @@ -52,9 +54,12 @@ GET /swagger.json | GET /openapi/v2 **Accept**: application/json GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 **Accept**: application/com.github.proto-openapi.spec.v2@v1.0+protobuf GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 **Accept**: application/com.github.proto-openapi.spec.v2@v1.0+protobuf **Accept-Encoding**: gzip - Kubernetes implements an alternative Protobuf based serialization format for the API that is primarily intended for intra-cluster communication, documented in the [design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md) and the IDL files for each schema are located in the Go packages that define the API objects. +Prior to 1.14, the Kubernetes apiserver also exposes an API that can be used to retrieve +the [Swagger v1.2](http://swagger.io/) Kubernetes API spec at `/swaggerapi`. +This endpoint is deprecated, and will be removed in Kubernetes 1.14. + ## API versioning To make it easier to eliminate fields or restructure resource representations, Kubernetes supports diff --git a/content/en/docs/reference/access-authn-authz/abac.md b/content/en/docs/reference/access-authn-authz/abac.md index 9174027776..40c56a985c 100644 --- a/content/en/docs/reference/access-authn-authz/abac.md +++ b/content/en/docs/reference/access-authn-authz/abac.md @@ -82,10 +82,9 @@ resource, and nonResourcePath properties set to `"*"`. ## Kubectl -Kubectl uses the `/api` and `/apis` endpoints of api-server to negotiate -client/server versions. To validate objects sent to the API by create/update -operations, kubectl queries certain swagger resources. For API version `v1` -those would be `/swaggerapi/api/v1` & `/swaggerapi/experimental/v1`. +Kubectl uses the `/api` and `/apis` endpoints of api-server to discover +served resource types, and validates objects sent to the API by create/update +operations using schema information located at `/openapi/v2`. When using ABAC authorization, those special resources have to be explicitly exposed via the `nonResourcePath` property in a policy (see [examples](#examples) below):