Skip to content

Commit

Permalink
Remove all docs which are moving to http://kubernetes.github.io
Browse files Browse the repository at this point in the history
All .md files now are only a pointer to where they likely are on the new
site.

All other files are untouched.
  • Loading branch information
eparis committed Mar 4, 2016
1 parent a20258e commit f334fc4
Show file tree
Hide file tree
Showing 134 changed files with 137 additions and 23,434 deletions.
37 changes: 1 addition & 36 deletions docs/admin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,42 +32,7 @@ Documentation for other releases can be found at

<!-- END MUNGE: UNVERSIONED_WARNING -->

# Kubernetes Cluster Admin Guide

The cluster admin guide is for anyone creating or administering a Kubernetes cluster.
It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md).

## Admin Guide Table of Contents

1. [Introduction](introduction.md)
1. [Components of a cluster](cluster-components.md)
1. [Cluster Management](cluster-management.md)
1. Kubernetes Master Components
1. [The kube-apiserver binary](kube-apiserver.md)
1. [Authorization](authorization.md)
1. [Authentication](authentication.md)
1. [Accessing the api](accessing-the-api.md)
1. [Admission Controllers](admission-controllers.md)
1. [Administrating Service Accounts](service-accounts-admin.md)
1. [Resource Quotas](resource-quota.md)
1. [The kube-scheduler binary](kube-scheduler.md)
1. [The kube-controller-manager binary](kube-controller-manager.md)
1. [Kubernetes Node Components](node.md)
1. [The kubelet binary](kubelet.md)
1. [Garbage Collection](garbage-collection.md)
1. [The kube-proxy binary](kube-proxy.md)
1. Cluster Addons
1. [DNS](dns.md)
1. [Networking](networking.md)
1. [OVS Networking](ovs-networking.md)
1. [Master <-> Node Communication](master-node-communication.md)
1. Example Configurations
1. [Multiple Clusters](multi-cluster.md)
1. [High Availability Clusters](high-availability.md)
1. [Large Clusters](cluster-large.md)
1. [Getting started from scratch](../getting-started-guides/scratch.md)
1. [Kubernetes's use of salt](salt.md)
1. [Troubleshooting](cluster-troubleshooting.md)
This file has moved to: http://kubernetes.github.io/docs/admin/README/


<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
Expand Down
66 changes: 1 addition & 65 deletions docs/admin/accessing-the-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,72 +32,8 @@ Documentation for other releases can be found at

<!-- END MUNGE: UNVERSIONED_WARNING -->

# Configuring APIserver ports
This file has moved to: http://kubernetes.github.io/docs/admin/accessing-the-api/

This document describes what ports the Kubernetes apiserver
may serve on and how to reach them. The audience is
cluster administrators who want to customize their cluster
or understand the details.

Most questions about accessing the cluster are covered
in [Accessing the cluster](../user-guide/accessing-the-cluster.md).


## Ports and IPs Served On

The Kubernetes API is served by the Kubernetes apiserver process. Typically,
there is one of these running on a single kubernetes-master node.

By default the Kubernetes APIserver serves HTTP on 2 ports:
1. Localhost Port
- serves HTTP
- default is port 8080, change with `--insecure-port` flag.
- defaults IP is localhost, change with `--insecure-bind-address` flag.
- no authentication or authorization checks in HTTP
- protected by need to have host access
2. Secure Port
- default is port 6443, change with `--secure-port` flag.
- default IP is first non-localhost network interface, change with `--bind-address` flag.
- serves HTTPS. Set cert with `--tls-cert-file` and key with `--tls-private-key-file` flag.
- uses token-file or client-certificate based [authentication](authentication.md).
- uses policy-based [authorization](authorization.md).
3. Removed: ReadOnly Port
- For security reasons, this had to be removed. Use the [service account](../user-guide/service-accounts.md) feature instead.

## Proxies and Firewall rules

Additionally, in some configurations there is a proxy (nginx) running
on the same machine as the apiserver process. The proxy serves HTTPS protected
by Basic Auth on port 443, and proxies to the apiserver on localhost:8080. In
these configurations the secure port is typically set to 6443.

A firewall rule is typically configured to allow external HTTPS access to port 443.

The above are defaults and reflect how Kubernetes is deployed to Google Compute Engine using
kube-up.sh. Other cloud providers may vary.

## Use Cases vs IP:Ports

There are three differently configured serving ports because there are a
variety of uses cases:
1. Clients outside of a Kubernetes cluster, such as human running `kubectl`
on desktop machine. Currently, accesses the Localhost Port via a proxy (nginx)
running on the `kubernetes-master` machine. The proxy can use cert-based authentication
or token-based authentication.
2. Processes running in Containers on Kubernetes that need to read from
the apiserver. Currently, these can use a [service account](../user-guide/service-accounts.md).
3. Scheduler and Controller-manager processes, which need to do read-write
API operations, using service accounts to avoid the need to be co-located.
4. Kubelets, which need to do read-write API operations and are necessarily
on different machines than the apiserver. Kubelet uses the Secure Port
to get their pods, to find the services that a pod can see, and to
write events. Credentials are distributed to kubelets at cluster
setup time. Kubelet and kube-proxy can use cert-based authentication or token-based
authentication.

## Expected changes

- Policy will limit the actions kubelets can do via the authed port.

<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/accessing-the-api.md?pixel)]()
Expand Down
165 changes: 1 addition & 164 deletions docs/admin/admission-controllers.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,170 +32,7 @@ Documentation for other releases can be found at

<!-- END MUNGE: UNVERSIONED_WARNING -->

# Admission Controllers

**Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->

- [Admission Controllers](#admission-controllers)
- [What are they?](#what-are-they)
- [Why do I need them?](#why-do-i-need-them)
- [How do I turn on an admission control plug-in?](#how-do-i-turn-on-an-admission-control-plug-in)
- [What does each plug-in do?](#what-does-each-plug-in-do)
- [AlwaysAdmit](#alwaysadmit)
- [AlwaysPullImages](#alwayspullimages)
- [AlwaysDeny](#alwaysdeny)
- [DenyExecOnPrivileged (deprecated)](#denyexeconprivileged-deprecated)
- [DenyEscalatingExec](#denyescalatingexec)
- [ServiceAccount](#serviceaccount)
- [SecurityContextDeny](#securitycontextdeny)
- [ResourceQuota](#resourcequota)
- [LimitRanger](#limitranger)
- [InitialResources (experimental)](#initialresources-experimental)
- [NamespaceExists (deprecated)](#namespaceexists-deprecated)
- [NamespaceAutoProvision (deprecated)](#namespaceautoprovision-deprecated)
- [NamespaceLifecycle](#namespacelifecycle)
- [Is there a recommended set of plug-ins to use?](#is-there-a-recommended-set-of-plug-ins-to-use)

<!-- END MUNGE: GENERATED_TOC -->

## What are they?

An admission control plug-in is a piece of code that intercepts requests to the Kubernetes
API server prior to persistence of the object, but after the request is authenticated
and authorized. The plug-in code is in the API server process
and must be compiled into the binary in order to be used at this time.

Each admission control plug-in is run in sequence before a request is accepted into the cluster. If
any of the plug-ins in the sequence reject the request, the entire request is rejected immediately
and an error is returned to the end-user.

Admission control plug-ins may mutate the incoming object in some cases to apply system configured
defaults. In addition, admission control plug-ins may mutate related resources as part of request
processing to do things like increment quota usage.

## Why do I need them?

Many advanced features in Kubernetes require an admission control plug-in to be enabled in order
to properly support the feature. As a result, a Kubernetes API server that is not properly
configured with the right set of admission control plug-ins is an incomplete server and will not
support all the features you expect.

## How do I turn on an admission control plug-in?

The Kubernetes API server supports a flag, `admission-control` that takes a comma-delimited,
ordered list of admission control choices to invoke prior to modifying objects in the cluster.

## What does each plug-in do?

### AlwaysAdmit

Use this plugin by itself to pass-through all requests.

### AlwaysPullImages

This plug-in modifies every new Pod to force the image pull policy to Always. This is useful in a
multitenant cluster so that users can be assured that their private images can only be used by those
who have the credentials to pull them. Without this plug-in, once an image has been pulled to a
node, any pod from any user can use it simply by knowing the image's name (assuming the Pod is
scheduled onto the right node), without any authorization check against the image. When this plug-in
is enabled, images are always pulled prior to starting containers, which means valid credentials are
required.

### AlwaysDeny

Rejects all requests. Used for testing.

### DenyExecOnPrivileged (deprecated)

This plug-in will intercept all requests to exec a command in a pod if that pod has a privileged container.

If your cluster supports privileged containers, and you want to restrict the ability of end-users to exec
commands in those containers, we strongly encourage enabling this plug-in.

This functionality has been merged into [DenyEscalatingExec](#denyescalatingexec).

### DenyEscalatingExec

This plug-in will deny exec and attach commands to pods that run with escalated privileges that
allow host access. This includes pods that run as privileged, have access to the host IPC namespace, and
have access to the host PID namespace.

If your cluster supports containers that run with escalated privileges, and you want to
restrict the ability of end-users to exec commands in those containers, we strongly encourage
enabling this plug-in.

### ServiceAccount

This plug-in implements automation for [serviceAccounts](../user-guide/service-accounts.md).
We strongly recommend using this plug-in if you intend to make use of Kubernetes `ServiceAccount` objects.

### SecurityContextDeny

This plug-in will deny any pod with a [SecurityContext](../user-guide/security-context.md) that defines options that were not available on the `Container`.

### ResourceQuota

This plug-in will observe the incoming request and ensure that it does not violate any of the constraints
enumerated in the `ResourceQuota` object in a `Namespace`. If you are using `ResourceQuota`
objects in your Kubernetes deployment, you MUST use this plug-in to enforce quota constraints.

See the [resourceQuota design doc](../design/admission_control_resource_quota.md) and the [example of Resource Quota](resourcequota/) for more details.

It is strongly encouraged that this plug-in is configured last in the sequence of admission control plug-ins. This is
so that quota is not prematurely incremented only for the request to be rejected later in admission control.

### LimitRanger

This plug-in will observe the incoming request and ensure that it does not violate any of the constraints
enumerated in the `LimitRange` object in a `Namespace`. If you are using `LimitRange` objects in
your Kubernetes deployment, you MUST use this plug-in to enforce those constraints. LimitRanger can also
be used to apply default resource requests to Pods that don't specify any; currently, the default LimitRanger
applies a 0.1 CPU requirement to all Pods in the `default` namespace.

See the [limitRange design doc](../design/admission_control_limit_range.md) and the [example of Limit Range](limitrange/) for more details.

### InitialResources (experimental)

This plug-in observes pod creation requests. If a container omits compute resource requests and limits,
then the plug-in auto-populates a compute resource request based on historical usage of containers running the same image.
If there is not enough data to make a decision the Request is left unchanged.
When the plug-in sets a compute resource request, it annotates the pod with information on what compute resources it auto-populated.

See the [InitialResouces proposal](../proposals/initial-resources.md) for more details.

### NamespaceExists (deprecated)

This plug-in will observe all incoming requests that attempt to create a resource in a Kubernetes `Namespace`
and reject the request if the `Namespace` was not previously created. We strongly recommend running
this plug-in to ensure integrity of your data.

The functionality of this admission controller has been merged into `NamespaceLifecycle`

### NamespaceAutoProvision (deprecated)

This plug-in will observe all incoming requests that attempt to create a resource in a Kubernetes `Namespace`
and create a new `Namespace` if one did not already exist previously.

We strongly recommend `NamespaceLifecycle` over `NamespaceAutoProvision`.

### NamespaceLifecycle

This plug-in enforces that a `Namespace` that is undergoing termination cannot have new objects created in it,
and ensures that requests in a non-existent `Namespace` are rejected.

A `Namespace` deletion kicks off a sequence of operations that remove all objects (pods, services, etc.) in that
namespace. In order to enforce integrity of that process, we strongly recommend running this plug-in.

## Is there a recommended set of plug-ins to use?

Yes.

For Kubernetes 1.0, we strongly recommend running the following set of admission control plug-ins (order matters):

```
--admission-control=NamespaceLifecycle,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota
```
This file has moved to: http://kubernetes.github.io/docs/admin/admission-controllers/


<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
Expand Down
Loading

0 comments on commit f334fc4

Please sign in to comment.