Merge pull request #24534 from sftim/20201012_use_overviews_in_reference_section
Use overviews in reference sectionpull/23842/head
Kubernetes Prow Robot
GitHub
commit
5384548617
|
|
@ -51,7 +51,7 @@ Before choosing a guide, here are some considerations:
|
|||
|
||||
* [Kubernetes Container Environment](/docs/concepts/containers/container-environment/) describes the environment for Kubelet managed containers on a Kubernetes node.
|
||||
|
||||
* [Controlling Access to the Kubernetes API](/docs/reference/access-authn-authz/controlling-access/) describes how to set up permissions for users and service accounts.
|
||||
* [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access) describes how Kubernetes implements access control for its own API.
|
||||
|
||||
* [Authenticating](/docs/reference/access-authn-authz/authentication/) explains authentication in Kubernetes, including the various authentication options.
|
||||
|
||||
|
|
|
|||
|
|
@ -130,7 +130,7 @@ Adding an API does not directly let you affect the behavior of existing APIs (e.
|
|||
|
||||
### API Access Extensions
|
||||
|
||||
When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then subject to various types of Admission Control. See [Controlling Access to the Kubernetes API](/docs/reference/access-authn-authz/controlling-access/) for more on this flow.
|
||||
When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then subject to various types of Admission Control. See [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/) for more on this flow.
|
||||
|
||||
Each of these steps offers extension points.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ methods for adding custom resources and how to choose between them.
|
|||
<!-- body -->
|
||||
## Custom resources
|
||||
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/reference/using-api/api-overview/) that stores a collection of
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/concepts/overview/kubernetes-api/) that stores a collection of
|
||||
[API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind; for example, the built-in *pods* resource contains a collection of Pod objects.
|
||||
|
||||
A *custom resource* is an extension of the Kubernetes API that is not necessarily available in a default
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ Adding an API does not directly let you affect the behavior of existing APIs (e.
|
|||
|
||||
### API Access Extensions
|
||||
|
||||
When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then subject to various types of Admission Control. See [Controlling Access to the Kubernetes API](/docs/reference/access-authn-authz/controlling-access/) for more on this flow.
|
||||
When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then subject to various types of Admission Control. See [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/) for more on this flow.
|
||||
|
||||
Each of these steps offers extension points.
|
||||
|
||||
|
|
|
|||
|
|
@ -103,8 +103,8 @@ and behavior, and to enable controlling access to end-of-life and/or
|
|||
experimental APIs.
|
||||
|
||||
To make it easier to evolve and to extend its API, Kubernetes implements
|
||||
[API groups](/docs/reference/using-api/api-overview/#api-groups) that can be
|
||||
[enabled or disabled](/docs/reference/using-api/api-overview/#enabling-or-disabling).
|
||||
[API groups](/docs/reference/using-api/#api-groups) that can be
|
||||
[enabled or disabled](/docs/reference/using-api/#enabling-or-disabling).
|
||||
|
||||
API resources are distinguished by their API group, resource type, namespace
|
||||
(for namespaced resources), and name. The API server may serve the same
|
||||
|
|
@ -115,7 +115,7 @@ versions `v1` and `v1beta1` for the same resource. An object created by the
|
|||
`v1beta1` version can then be read, updated, and deleted by either the
|
||||
`v1beta1` or the `v1` versions.
|
||||
|
||||
Refer to [API versions reference](/docs/reference/using-api/api-overview/#api-versioning)
|
||||
Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
|
||||
for more details on the API version level definitions.
|
||||
|
||||
## API Extension
|
||||
|
|
@ -131,7 +131,7 @@ The Kubernetes API can be extended in one of two ways:
|
|||
|
||||
- Learn how to extend the Kubernetes API by adding your own
|
||||
[CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).
|
||||
- [Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes
|
||||
- [Controlling Access To The Kubernetes API](/docs/concepts/security/controlling-access/) describes
|
||||
how the cluster manages authentication and authorization for API access.
|
||||
- Learn about API endpoints, resource types and samples by reading
|
||||
[API Reference](/docs/reference/kubernetes-api/).
|
||||
|
|
|
|||
|
|
@ -91,9 +91,9 @@ and the `spec` format for a Deployment can be found in
|
|||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [Kubernetes API overview](/docs/reference/using-api/api-overview/) explains some more API concepts
|
||||
* Learn about the most important basic Kubernetes objects, such as [Pod](/docs/concepts/workloads/pods/).
|
||||
* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes
|
||||
* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes.
|
||||
* [Using the Kubernetes API](/docs/reference/using-api/) explains some more API concepts.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -140,13 +140,17 @@ For a complete example of authorizing a PodSecurityPolicy, see
|
|||
|
||||
### Troubleshooting
|
||||
|
||||
- The [Controller Manager](/docs/reference/command-line-tools-reference/kube-controller-manager/) must be run
|
||||
against [the secured API port](/docs/reference/access-authn-authz/controlling-access/),
|
||||
and must not have superuser permissions. Otherwise requests would bypass
|
||||
authentication and authorization modules, all PodSecurityPolicy objects would be
|
||||
allowed, and users would be able to create privileged containers. For more details
|
||||
on configuring Controller Manager authorization, see
|
||||
[Controller Roles](/docs/reference/access-authn-authz/rbac/#controller-roles).
|
||||
- The [controller manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
|
||||
must be run against the secured API port and must not have superuser permissions. See
|
||||
[Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access)
|
||||
to learn about API server access controls.
|
||||
If the controller manager connected through the trusted API port (also known as the
|
||||
`localhost` listener), requests would bypass authentication and authorization modules;
|
||||
all PodSecurityPolicy objects would be allowed, and users would be able to create grant
|
||||
themselves the ability to create privileged containers.
|
||||
|
||||
For more details on configuring controller manager authorization, see
|
||||
[Controller Roles](/docs/reference/access-authn-authz/rbac/#controller-roles).
|
||||
|
||||
## Policy Order
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,6 @@ reviewers:
|
|||
- lavalamp
|
||||
title: Controlling Access to the Kubernetes API
|
||||
content_type: concept
|
||||
weight: 5
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
|
@ -12,7 +11,7 @@ This page provides an overview of controlling access to the Kubernetes API.
|
|||
|
||||
|
||||
<!-- body -->
|
||||
Users [access the API](/docs/tasks/access-application-cluster/access-cluster/) using `kubectl`,
|
||||
Users access the [Kubernetes API](/docs/concepts/overview/kubernetes-api/) using `kubectl`,
|
||||
client libraries, or by making REST requests. Both human users and
|
||||
[Kubernetes service accounts](/docs/tasks/configure-pod-container/configure-service-account/) can be
|
||||
authorized for API access.
|
||||
|
|
@ -21,45 +20,46 @@ following diagram:
|
|||
|
||||
|
||||
|
||||
## Transport Security
|
||||
## Transport security
|
||||
|
||||
In a typical Kubernetes cluster, the API serves on port 443.
|
||||
The API server presents a certificate. This certificate is
|
||||
often self-signed, so `$USER/.kube/config` on the user's machine typically
|
||||
contains the root certificate for the API server's certificate, which when specified
|
||||
is used in place of the system default root certificate. This certificate is typically
|
||||
automatically written into your `$USER/.kube/config` when you create a cluster yourself
|
||||
using `kube-up.sh`. If the cluster has multiple users, then the creator needs to share
|
||||
the certificate with other users.
|
||||
In a typical Kubernetes cluster, the API serves on port 443, protected by TLS.
|
||||
The API server presents a certificate. This certificate may be signed using
|
||||
a private certificate authority (CA), or based on a public key infrastructure linked
|
||||
to a generally recognized CA.
|
||||
|
||||
If your cluster uses a private certificate authority, you need a copy of that CA
|
||||
certifcate configured into your `~/.kube/config` on the client, so that you can
|
||||
trust the connection and be confident it was not intercepted.
|
||||
|
||||
Your client can present a TLS client certificate at this stage.
|
||||
|
||||
## Authentication
|
||||
|
||||
Once TLS is established, the HTTP request moves to the Authentication step.
|
||||
This is shown as step **1** in the diagram.
|
||||
The cluster creation script or cluster admin configures the API server to run
|
||||
one or more Authenticator Modules.
|
||||
Authenticators are described in more detail [here](/docs/reference/access-authn-authz/authentication/).
|
||||
one or more Authenticator modules.
|
||||
Authenticators are described in more detail in
|
||||
[Authentication](/docs/reference/access-authn-authz/authentication/).
|
||||
|
||||
The input to the authentication step is the entire HTTP request, however, it typically
|
||||
The input to the authentication step is the entire HTTP request; however, it typically
|
||||
just examines the headers and/or client certificate.
|
||||
|
||||
Authentication modules include Client Certificates, Password, and Plain Tokens,
|
||||
Bootstrap Tokens, and JWT Tokens (used for service accounts).
|
||||
Authentication modules include client certificates, password, and plain tokens,
|
||||
bootstrap tokens, and JSON Web Tokens (used for service accounts).
|
||||
|
||||
Multiple authentication modules can be specified, in which case each one is tried in sequence,
|
||||
until one of them succeeds.
|
||||
|
||||
On GCE, Client Certificates, Password, Plain Tokens, and JWT Tokens are all enabled.
|
||||
|
||||
If the request cannot be authenticated, it is rejected with HTTP status code 401.
|
||||
Otherwise, the user is authenticated as a specific `username`, and the user name
|
||||
is available to subsequent steps to use in their decisions. Some authenticators
|
||||
also provide the group memberships of the user, while other authenticators
|
||||
do not.
|
||||
|
||||
While Kubernetes uses `usernames` for access control decisions and in request logging,
|
||||
it does not have a `user` object nor does it store usernames or other information about
|
||||
users in its object store.
|
||||
While Kubernetes uses usernames for access control decisions and in request logging,
|
||||
it does not have a `User` object nor does it store usernames or other information about
|
||||
users in its API.
|
||||
|
||||
## Authorization
|
||||
|
||||
|
|
@ -101,16 +101,16 @@ If Bob makes a request to write (`create` or `update`) to the objects in the `pr
|
|||
|
||||
Kubernetes authorization requires that you use common REST attributes to interact with existing organization-wide or cloud-provider-wide access control systems. It is important to use REST formatting because these control systems might interact with other APIs besides the Kubernetes API.
|
||||
|
||||
Kubernetes supports multiple authorization modules, such as ABAC mode, RBAC Mode, and Webhook mode. When an administrator creates a cluster, they configured the authorization modules that should be used in the API server. If more than one authorization modules are configured, Kubernetes checks each module, and if any module authorizes the request, then the request can proceed. If all of the modules deny the request, then the request is denied (HTTP status code 403).
|
||||
Kubernetes supports multiple authorization modules, such as ABAC mode, RBAC Mode, and Webhook mode. When an administrator creates a cluster, they configure the authorization modules that should be used in the API server. If more than one authorization modules are configured, Kubernetes checks each module, and if any module authorizes the request, then the request can proceed. If all of the modules deny the request, then the request is denied (HTTP status code 403).
|
||||
|
||||
To learn more about Kubernetes authorization, including details about creating policies using the supported authorization modules, see [Authorization Overview](/docs/reference/access-authn-authz/authorization/).
|
||||
To learn more about Kubernetes authorization, including details about creating policies using the supported authorization modules, see [Authorization](/docs/reference/access-authn-authz/authorization/).
|
||||
|
||||
|
||||
## Admission Control
|
||||
## Admission control
|
||||
|
||||
Admission Control Modules are software modules that can modify or reject requests.
|
||||
In addition to the attributes available to Authorization Modules, Admission
|
||||
Control Modules can access the contents of the object that is being created or modified.
|
||||
Admission Control modules are software modules that can modify or reject requests.
|
||||
In addition to the attributes available to Authorization modules, Admission
|
||||
Control modules can access the contents of the object that is being created or modified.
|
||||
|
||||
Admission controllers act on requests that create, modify, delete, or connect to (proxy) an object.
|
||||
Admission controllers do not act on requests that merely read objects.
|
||||
|
|
@ -118,26 +118,26 @@ When multiple admission controllers are configured, they are called in order.
|
|||
|
||||
This is shown as step **3** in the diagram.
|
||||
|
||||
Unlike Authentication and Authorization Modules, if any admission controller module
|
||||
Unlike Authentication and Authorization modules, if any admission controller module
|
||||
rejects, then the request is immediately rejected.
|
||||
|
||||
In addition to rejecting objects, admission controllers can also set complex defaults for
|
||||
fields.
|
||||
|
||||
The available Admission Control Modules are described [here](/docs/reference/access-authn-authz/admission-controllers/).
|
||||
The available Admission Control modules are described in [Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/).
|
||||
|
||||
Once a request passes all admission controllers, it is validated using the validation routines
|
||||
for the corresponding API object, and then written to the object store (shown as step **4**).
|
||||
|
||||
|
||||
## API Server Ports and IPs
|
||||
## API server ports and IPs
|
||||
|
||||
The previous discussion applies to requests sent to the secure port of the API server
|
||||
(the typical case). The API server can actually serve on 2 ports:
|
||||
|
||||
By default the Kubernetes API server serves HTTP on 2 ports:
|
||||
|
||||
1. `Localhost Port`:
|
||||
1. `localhost` port:
|
||||
|
||||
- is intended for testing and bootstrap, and for other components of the master node
|
||||
(scheduler, controller-manager) to talk to the API
|
||||
|
|
@ -148,7 +148,7 @@ By default the Kubernetes API server serves HTTP on 2 ports:
|
|||
- request handled by admission control module(s).
|
||||
- protected by need to have host access
|
||||
|
||||
2. `Secure Port`:
|
||||
2. “Secure port”:
|
||||
|
||||
- use whenever possible
|
||||
- uses TLS. Set cert with `--tls-cert-file` and key with `--tls-private-key-file` flag.
|
||||
|
|
@ -158,8 +158,27 @@ By default the Kubernetes API server serves HTTP on 2 ports:
|
|||
- request handled by admission control module(s).
|
||||
- authentication and authorization modules run.
|
||||
|
||||
When the cluster is created by `kube-up.sh`, on Google Compute Engine (GCE),
|
||||
and on several other cloud providers, the API server serves on port 443. On
|
||||
GCE, a firewall rule is configured on the project to allow external HTTPS
|
||||
access to the API. Other cluster setup methods vary.
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
Read more documentation on authentication, authorization and API access control:
|
||||
|
||||
- [Authenticating](/docs/reference/access-authn-authz/authentication/)
|
||||
- [Authenticating with Bootstrap Tokens](/docs/reference/access-authn-authz/bootstrap-tokens/)
|
||||
- [Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/)
|
||||
- [Dynamic Admission Control](/docs/reference/access-authn-authz/extensible-admission-controllers/)
|
||||
- [Authorization](/docs/reference/access-authn-authz/authorization/)
|
||||
- [Role Based Access Control](/docs/reference/access-authn-authz/rbac/)
|
||||
- [Attribute Based Access Control](/docs/reference/access-authn-authz/abac/)
|
||||
- [Node Authorization](/docs/reference/access-authn-authz/node/)
|
||||
- [Webhook Authorization](/docs/reference/access-authn-authz/webhook/)
|
||||
- [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/)
|
||||
- including [CSR approval](/docs/reference/access-authn-authz/certificate-signing-requests/#approval-rejection)
|
||||
and [certificate signing](/docs/reference/access-authn-authz/certificate-signing-requests/#signing)
|
||||
- Service accounts
|
||||
- [Developer guide](/docs/tasks/configure-pod-container/configure-service-account/)
|
||||
- [Administration](/docs/reference/access-authn-authz/service-accounts-admin/)
|
||||
|
||||
You can learn about:
|
||||
- how Pods can use
|
||||
[Secrets](/docs/concepts/configuration/secret/#service-accounts-automatically-create-and-attach-secrets-with-api-credentials)
|
||||
to obtain API credentials.
|
||||
|
|
@ -103,7 +103,7 @@ areas of security concerns and recommendations for securing workloads running in
|
|||
Area of Concern for Workload Security | Recommendation |
|
||||
------------------------------ | --------------------- |
|
||||
RBAC Authorization (Access to the Kubernetes API) | https://kubernetes.io/docs/reference/access-authn-authz/rbac/
|
||||
Authentication | https://kubernetes.io/docs/reference/access-authn-authz/controlling-access/
|
||||
Authentication | https://kubernetes.io/docs/concepts/security/controlling-access/
|
||||
Application secrets management (and encrypting them in etcd at rest) | https://kubernetes.io/docs/concepts/configuration/secret/ <br> https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/
|
||||
Pod Security Policies | https://kubernetes.io/docs/concepts/policy/pod-security-policy/
|
||||
Quality of Service (and Cluster resource management) | https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/
|
||||
|
|
@ -147,8 +147,8 @@ Learn about related Kubernetes security topics:
|
|||
|
||||
* [Pod security standards](/docs/concepts/security/pod-security-standards/)
|
||||
* [Network policies for Pods](/docs/concepts/services-networking/network-policies/)
|
||||
* [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access)
|
||||
* [Securing your cluster](/docs/tasks/administer-cluster/securing-a-cluster/)
|
||||
* [API access control](/docs/reference/access-authn-authz/controlling-access/)
|
||||
* [Data encryption in transit](/docs/tasks/tls/managing-tls-in-a-cluster/) for the control plane
|
||||
* [Data encryption at rest](/docs/tasks/administer-cluster/encrypt-data/)
|
||||
* [Secrets in Kubernetes](/docs/concepts/configuration/secret/)
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@ This section of the Kubernetes documentation contains references.
|
|||
|
||||
## API Reference
|
||||
|
||||
* [Kubernetes API Overview](/docs/reference/using-api/api-overview/) - Overview of the API for Kubernetes.
|
||||
* [Kubernetes API Reference {{< latest-version >}}](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/)
|
||||
* [Using The Kubernetes API](/docs/reference/using-api/) - overview of the API for Kubernetes.
|
||||
|
||||
## API Client Libraries
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,26 @@
|
|||
---
|
||||
title: Accessing the API
|
||||
title: API Access Control
|
||||
weight: 20
|
||||
---
|
||||
no_list: true
|
||||
---
|
||||
|
||||
For an introduction to how Kubernetes implements and controls API access,
|
||||
read [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/).
|
||||
|
||||
Reference documentation:
|
||||
|
||||
- [Authenticating](/docs/reference/access-authn-authz/authentication/)
|
||||
- [Authenticating with Bootstrap Tokens](/docs/reference/access-authn-authz/bootstrap-tokens/)
|
||||
- [Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/)
|
||||
- [Dynamic Admission Control](/docs/reference/access-authn-authz/extensible-admission-controllers/)
|
||||
- [Authorization](/docs/reference/access-authn-authz/authorization/)
|
||||
- [Role Based Access Control](/docs/reference/access-authn-authz/rbac/)
|
||||
- [Attribute Based Access Control](/docs/reference/access-authn-authz/abac/)
|
||||
- [Node Authorization](/docs/reference/access-authn-authz/node/)
|
||||
- [Webhook Authorization](/docs/reference/access-authn-authz/webhook/)
|
||||
- [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/)
|
||||
- including [CSR approval](/docs/reference/access-authn-authz/certificate-signing-requests/#approval-rejection)
|
||||
and [certificate signing](/docs/reference/access-authn-authz/certificate-signing-requests/#signing)
|
||||
- Service accounts
|
||||
- [Developer guide](/docs/tasks/configure-pod-container/configure-service-account/)
|
||||
- [Administration](/docs/reference/access-authn-authz/service-accounts-admin/)
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ policies using the supported authorization modules.
|
|||
<!-- body -->
|
||||
In Kubernetes, you must be authenticated (logged in) before your request can be
|
||||
authorized (granted permission to access). For information about authentication,
|
||||
see [Controlling Access to the Kubernetes API](/docs/reference/access-authn-authz/controlling-access/).
|
||||
see [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/).
|
||||
|
||||
Kubernetes expects attributes that are common to REST API requests. This means
|
||||
that Kubernetes authorization works with existing organization-wide or
|
||||
|
|
@ -52,7 +52,7 @@ Kubernetes reviews only the following API request attributes:
|
|||
* **Resource** - The ID or name of the resource that is being accessed (for resource requests only) -- For resource requests using `get`, `update`, `patch`, and `delete` verbs, you must provide the resource name.
|
||||
* **Subresource** - The subresource that is being accessed (for resource requests only).
|
||||
* **Namespace** - The namespace of the object that is being accessed (for namespaced resource requests only).
|
||||
* **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the [core API group](/docs/reference/using-api/api-overview/#api-groups).
|
||||
* **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the _core_ [API group](/docs/reference/using-api/#api-groups).
|
||||
|
||||
## Determine the Request Verb
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,132 @@
|
|||
---
|
||||
title: Using the Kubernetes API
|
||||
title: Kubernetes API Overview
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- jbeda
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
card:
|
||||
name: reference
|
||||
weight: 50
|
||||
title: Overview of API
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This section provides reference information for the Kubernetes API.
|
||||
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||
communications between components, and external user commands are REST API
|
||||
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
The [Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
|
||||
lists the API for Kubernetes version {{< param "version" >}}.
|
||||
|
||||
For general background information, read
|
||||
[The Kubernetes API](/docs/concepts/overview/kubernetes-api/).
|
||||
[Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/)
|
||||
describes how clients can authenticate to the Kubernetes API server, and how their
|
||||
requests are authorized.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||
communications between components, and external user commands are REST API
|
||||
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
API.
|
||||
|
||||
## API versioning
|
||||
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||
schema changes. The following descriptions cover both formats.
|
||||
|
||||
The API versioning and software versioning are indirectly related.
|
||||
The [API and release versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
|
||||
describes the relationship between API versioning and software versioning.
|
||||
|
||||
Different API versions indicate different levels of stability and support. You
|
||||
can find more information about the criteria for each level in the
|
||||
[API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
||||
|
||||
Here's a summary of each level:
|
||||
|
||||
- Alpha:
|
||||
- The version names contain `alpha` (for example, `v1alpha1`).
|
||||
- The software may contain bugs. Enabling a feature may expose bugs. A
|
||||
feature may be disabled by default.
|
||||
- The support for a feature may be dropped at any time without notice.
|
||||
- The API may change in incompatible ways in a later software release without notice.
|
||||
- The software is recommended for use only in short-lived testing clusters,
|
||||
due to increased risk of bugs and lack of long-term support.
|
||||
|
||||
- Beta:
|
||||
- The version names contain `beta` (for example, `v2beta3`).
|
||||
- The software is well tested. Enabling a feature is considered safe.
|
||||
Features are enabled by default.
|
||||
- The support for a feature will not be dropped, though the details may change.
|
||||
|
||||
- The schema and/or semantics of objects may change in incompatible ways in
|
||||
a subsequent beta or stable release. When this happens, migration
|
||||
instructions are provided. Schema changes may require deleting, editing, and
|
||||
re-creating API objects. The editing process may not be straightforward.
|
||||
The migration may require downtime for applications that rely on the feature.
|
||||
- The software is not recommended for production uses. Subsequent releases
|
||||
may introduce incompatible changes. If you have multiple clusters which
|
||||
can be upgraded independently, you may be able to relax this restriction.
|
||||
|
||||
{{< note >}}
|
||||
Please try beta features and provide feedback. After the features exit beta, it
|
||||
may not be practical to make more changes.
|
||||
{{< /note >}}
|
||||
|
||||
- Stable:
|
||||
- The version name is `vX` where `X` is an integer.
|
||||
- The stable versions of features appear in released software for many subsequent versions.
|
||||
|
||||
## API groups
|
||||
|
||||
[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)
|
||||
make it easier to extend the Kubernetes API.
|
||||
The API group is specified in a REST path and in the `apiVersion` field of a
|
||||
serialized object.
|
||||
|
||||
There are several API groups in Kubernetes:
|
||||
|
||||
* The *core* (also called *legacy*) group is found at REST path `/api/v1`.
|
||||
The core group is not specified as part of the `apiVersion` field, for
|
||||
example, `apiVersion: v1`.
|
||||
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
|
||||
`apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
|
||||
You can find the full list of supported API groups in
|
||||
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-).
|
||||
|
||||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||
|
||||
Certain resources and API groups are enabled by default. You can enable or
|
||||
disable them by setting `--runtime-config` on the API server. The
|
||||
`--runtime-config` flag accepts comma separated `<key>[=<value>]` pairs
|
||||
describing the runtime configuration of the API server. If the `=<value>`
|
||||
part is omitted, it is treated as if `=true` is specified. For example:
|
||||
|
||||
- to disable `batch/v1`, set `--runtime-config=batch/v1=false`
|
||||
- to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
|
||||
|
||||
{{< note >}}
|
||||
When you enable or disable groups or resources, you need to restart the API
|
||||
server and controller manager to pick up the `--runtime-config` changes.
|
||||
{{< /note >}}
|
||||
|
||||
## Persistence
|
||||
|
||||
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
||||
{{< glossary_tooltip term_id="etcd" >}}.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||||
- Read the design documentation for
|
||||
[aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)
|
||||
|
|
|
|||
|
|
@ -1,118 +0,0 @@
|
|||
---
|
||||
title: Kubernetes API Overview
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- jbeda
|
||||
content_type: concept
|
||||
weight: 10
|
||||
card:
|
||||
name: reference
|
||||
weight: 50
|
||||
title: Overview of API
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This page provides an overview of the Kubernetes API.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||
communications between components, and external user commands are REST API
|
||||
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
## API versioning
|
||||
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||
schema changes. The following descriptions cover both formats.
|
||||
|
||||
The API versioning and software versioning are indirectly related.
|
||||
The [API and release versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
|
||||
describes the relationship between API versioning and software versioning.
|
||||
|
||||
Different API versions indicate different levels of stability and support. You
|
||||
can find more information about the criteria for each level in the
|
||||
[API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
||||
|
||||
Here's a summary of each level:
|
||||
|
||||
- Alpha:
|
||||
- The version names contain `alpha` (for example, `v1alpha1`).
|
||||
- The software may contain bugs. Enabling a feature may expose bugs. A
|
||||
feature may be disabled by default.
|
||||
- The support for a feature may be dropped at any time without notice.
|
||||
- The API may change in incompatible ways in a later software release without notice.
|
||||
- The software is recommended for use only in short-lived testing clusters,
|
||||
due to increased risk of bugs and lack of long-term support.
|
||||
|
||||
- Beta:
|
||||
- The version names contain `beta` (for example, `v2beta3`).
|
||||
- The software is well tested. Enabling a feature is considered safe.
|
||||
Features are enabled by default.
|
||||
- The support for a feature will not be dropped, though the details may change.
|
||||
|
||||
- The schema and/or semantics of objects may change in incompatible ways in
|
||||
a subsequent beta or stable release. When this happens, migration
|
||||
instructions are provided. Schema changes may require deleting, editing, and
|
||||
re-creating API objects. The editing process may not be straightforward.
|
||||
The migration may require downtime for applications that rely on the feature.
|
||||
- The software is not recommended for production uses. Subsequent releases
|
||||
may introduce incompatible changes. If you have multiple clusters which
|
||||
can be upgraded independently, you may be able to relax this restriction.
|
||||
|
||||
{{< note >}}
|
||||
Try the beta features and provide feedback. After the features exit beta, it
|
||||
may not be practical to make more changes.
|
||||
{{< /note >}}
|
||||
|
||||
- Stable:
|
||||
- The version name is `vX` where `X` is an integer.
|
||||
- The stable versions of features appear in released software for many subsequent versions.
|
||||
|
||||
## API groups
|
||||
|
||||
[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)
|
||||
make it easier to extend the Kubernetes API.
|
||||
The API group is specified in a REST path and in the `apiVersion` field of a
|
||||
serialized object.
|
||||
|
||||
Currently, there are several API groups in use:
|
||||
|
||||
* The *core* (also called *legacy*) group is found at REST path `/api/v1`.
|
||||
The core group is not specified as part of the `apiVersion` field, for
|
||||
example, `apiVersion: v1`.
|
||||
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
|
||||
`apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
|
||||
You can find the full list of supported API groups in
|
||||
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-).
|
||||
|
||||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||
|
||||
Certain resources and API groups are enabled by default. You can enable or
|
||||
disable them by setting `--runtime-config` on the API server. The
|
||||
`--runtime-config` flag accepts comma separated `<key>[=<value>]` pairs
|
||||
describing the runtime configuration of the API server. If the `=<value>`
|
||||
part is omitted, it is treated as if `=true` is specified. For example:
|
||||
|
||||
- to disable `batch/v1`, set `--runtime-config=batch/v1=false`
|
||||
- to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
|
||||
|
||||
{{< note >}}
|
||||
When you enable or disable groups or resources, you need to restart the API
|
||||
server and controller manager to pick up the `--runtime-config` changes.
|
||||
{{< /note >}}
|
||||
|
||||
## Persistence
|
||||
|
||||
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
||||
{{< glossary_tooltip term_id="etcd" >}}.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||||
- Read the design documentation for
|
||||
[aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ API from various programming languages.
|
|||
|
||||
|
||||
<!-- body -->
|
||||
To write applications using the [Kubernetes REST API](/docs/reference/using-api/api-overview/),
|
||||
To write applications using the [Kubernetes REST API](/docs/reference/using-api/),
|
||||
you do not need to implement the API calls and request/response types yourself.
|
||||
You can use a client library for the programming language you are using.
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ a deprecation policy for aspects of the system that are slated to be removed.
|
|||
Since Kubernetes is an API-driven system, the API has evolved over time to
|
||||
reflect the evolving understanding of the problem space. The Kubernetes API is
|
||||
actually a set of APIs, called "API groups", and each API group is
|
||||
independently versioned. [API versions](/docs/reference/using-api/api-overview/#api-versioning) fall
|
||||
independently versioned. [API versions](/docs/reference/using-api/#api-versioning) fall
|
||||
into 3 main tracks, each of which has different policies for deprecation:
|
||||
|
||||
| Example | Track |
|
||||
|
|
|
|||
|
|
@ -149,9 +149,8 @@ certificate.
|
|||
|
||||
On some clusters, the apiserver does not require authentication; it may serve
|
||||
on localhost, or be protected by a firewall. There is not a standard
|
||||
for this. [Configuring Access to the API](/docs/reference/access-authn-authz/controlling-access/)
|
||||
describes how a cluster admin can configure this. Such approaches may conflict
|
||||
with future high-availability support.
|
||||
for this. [Controlling Access to the API](/docs/concepts/security/controlling-access)
|
||||
describes how a cluster admin can configure this.
|
||||
|
||||
## Programmatic access to the API
|
||||
|
||||
|
|
|
|||
|
|
@ -148,9 +148,8 @@ certificate.
|
|||
|
||||
On some clusters, the API server does not require authentication; it may serve
|
||||
on localhost, or be protected by a firewall. There is not a standard
|
||||
for this. [Configuring Access to the API](/docs/reference/access-authn-authz/controlling-access/)
|
||||
describes how a cluster admin can configure this. Such approaches may conflict
|
||||
with future high-availability support.
|
||||
for this. [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access)
|
||||
describes how you can configure this as a cluster administrator.
|
||||
|
||||
### Programmatic access to the API
|
||||
|
||||
|
|
|
|||
|
|
@ -68,6 +68,8 @@
|
|||
/docs/api/ /docs/concepts/overview/kubernetes-api/ 301
|
||||
|
||||
/docs/api-reference/labels-annotations-taints/ /docs/reference/labels-annotations-taints/ 301
|
||||
/docs/reference/using-api/api-overview/ /docs/reference/using-api/ 301
|
||||
/docs/reference/access-authn-authz/controlling-access/ /docs/concepts/security/controlling-access/ 301
|
||||
|
||||
/docs/concepts/abstractions/controllers/garbage-collection/ /docs/concepts/workloads/controllers/garbage-collection/ 301
|
||||
/docs/concepts/abstractions/controllers/statefulsets/ /docs/concepts/workloads/controllers/statefulset/ 301
|
||||
|
|
@ -448,7 +450,8 @@
|
|||
/editdocs/ /docs/contribute/ 301
|
||||
/docs/home/editdocs/ /docs/contribute/ 301
|
||||
|
||||
/docs/admin/accessing-the-api/ /docs/reference/access-authn-authz/controlling-access/ 301
|
||||
|
||||
/docs/admin/accessing-the-api/ /docs/concepts/overview/kubernetes-api/ 301
|
||||
/docs/admin/admission-controllers/ /docs/reference/access-authn-authz/admission-controllers/ 301
|
||||
/docs/admin/authentication/ /docs/reference/access-authn-authz/authentication/ 301
|
||||
/docs/admin/bootstrap-tokens/ /docs/reference/access-authn-authz/bootstrap-tokens/ 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue