github/kubernetes
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move some docs from docs/ top-level into docs/{admin/,devel/,user-guide/}.

Browse Source
This commit is contained in:
David Oppenheimer
2015-07-14 22:07:44 -07:00
parent cdc74dde4c
commit 8d5eb03c7b
28 changed files with 58 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/user-guide/README.md
View File

@@ -32,7 +32,7 @@ certainly want the docs that go with that version.</h1>
<!-- END MUNGE: GENERATED_TOC -->
The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster. Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/developer-guide.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project.
The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster. Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/devel/developer-guide.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project.
Please ensure you have completed the [prerequisites for running examples from the user guide](prereqs.md).

4
docs/user-guide/accessing-the-cluster.md
View File

@@ -124,7 +124,7 @@ with future high-availability support.
### Programmatic access to the API
There are [client libraries](../client-libraries.md) for accessing the API
There are [client libraries](../devel/client-libraries.md) for accessing the API
from several languages. The Kubernetes project-supported
[Go](https://github.com/GoogleCloudPlatform/kubernetes/tree/master/pkg/client)
client library can use the same [kubeconfig file](kubeconfig-file.md)
@@ -142,7 +142,7 @@ the `kubernetes` DNS name, which resolves to a Service IP which in turn
will be routed to an apiserver.
The recommended way to authenticate to the apiserver is with a
[service account](../service-accounts.md) credential. By default, a pod
[service account](service-accounts.md) credential. By default, a pod
is associated with a service account, and a credential (token) for that
service account is placed into the filesystem tree of each container in that pod,
at `/var/run/secrets/kubernetes.io/serviceaccount/token`.

2
docs/user-guide/application-troubleshooting.md
View File

@@ -24,7 +24,7 @@ certainly want the docs that go with that version.</h1>
This guide is to help users debug applications that are deployed into Kubernetes and not behaving correctly.
This is *not* a guide for people who want to debug their cluster. For that you should check out
[this guide](../cluster-troubleshooting.md)
[this guide](../admin/cluster-troubleshooting.md)
**Table of Contents**
<!-- BEGIN MUNGE: GENERATED_TOC -->

2
docs/user-guide/images.md
View File

@@ -223,7 +223,7 @@ spec:
```
This needs to be done for each pod that is using a private registry.
However, setting of this field can be automated by setting the imagePullSecrets
in a [serviceAccount](../service-accounts.md) resource.
in a [serviceAccount](service-accounts.md) resource.
Currently, all pods will potentially have read access to any images which were
pulled using imagePullSecrets. That is, imagePullSecrets does *NOT* protect your

2
docs/user-guide/pod-states.md
View File

@@ -28,7 +28,7 @@ This document covers the lifecycle of a pod. It is not an exhaustive document,
## Pod Phase
As consistent with the overall [API convention](../api-conventions.md#typical-status-properties), phase is a simple, high-level summary of the phase of the lifecycle of a pod. It is not intended to be a comprehensive rollup of observations of container-level or even pod-level conditions or other state, nor is it intended to be a comprehensive state machine.
As consistent with the overall [API convention](../devel/api-conventions.md#typical-status-properties), phase is a simple, high-level summary of the phase of the lifecycle of a pod. It is not intended to be a comprehensive rollup of observations of container-level or even pod-level conditions or other state, nor is it intended to be a comprehensive state machine.
The number and meanings of `PodPhase` values are tightly guarded. Other than what is documented here, nothing should be assumed about pods with a given `PodPhase`.

8
docs/user-guide/secrets.md
View File

@@ -74,7 +74,7 @@ The automatic creation and use of API credentials can be disabled or overridden
if desired. However, if all you need to do is securely access the apiserver,
this is the recommended workflow.
See the [Service Account](../service-accounts.md) documentation for more
See the [Service Account](service-accounts.md) documentation for more
information on how Service Accounts work.
### Creating a Secret Manually
@@ -100,7 +100,7 @@ are `value-1` and `value-2`, respectively, with carriage return and newline char
Create the secret using [`kubectl create`](kubectl/kubectl_create.md).
Once the secret is created, you can:
- create pods that automatically use it via a [Service Account](../service-accounts.md).
- create pods that automatically use it via a [Service Account](service-accounts.md).
- modify your pod specification to use the secret
### Manually specifying a Secret to be Mounted on a Pod
@@ -149,7 +149,7 @@ Use of imagePullSecrets is desribed in the [images documentation](images.md#spec
*This feature is planned but not implemented. See [issue
9902](https://github.com/GoogleCloudPlatform/kubernetes/issues/9902).*
You can reference manually created secrets from a [service account](../service-accounts.md).
You can reference manually created secrets from a [service account](service-accounts.md).
Then, pods which use that service account will have
`volumeMounts` and/or `imagePullSecrets` added to them.
The secrets will be mounted at **TBD**.
@@ -217,7 +217,7 @@ the original pod must be deleted, and a new pod (perhaps with an identical
workflow as deploying a new container image. The `kubectl rolling-update`
command can be used ([man page](kubectl/kubectl_rolling-update.md)).
The [`resourceVersion`](../api-conventions.md#concurrency-control-and-consistency)
The [`resourceVersion`](../devel/api-conventions.md#concurrency-control-and-consistency)
of the secret is not specified when it is referenced.
Therefore, if a secret is updated at about the same time as pods are starting,
then it is not defined which version of the secret will be used for the pod. It

117
docs/user-guide/service-accounts.md Normal file
View File

@@ -0,0 +1,117 @@
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
<!-- BEGIN STRIP_FOR_RELEASE -->
![WARNING](http://kubernetes.io/img/warning.png)
![WARNING](http://kubernetes.io/img/warning.png)
![WARNING](http://kubernetes.io/img/warning.png)
<h1>PLEASE NOTE: This document applies to the HEAD of the source
tree only. If you are using a released version of Kubernetes, you almost
certainly want the docs that go with that version.</h1>
<strong>Documentation for specific releases can be found at
[releases.k8s.io](http://releases.k8s.io).</strong>
![WARNING](http://kubernetes.io/img/warning.png)
![WARNING](http://kubernetes.io/img/warning.png)
![WARNING](http://kubernetes.io/img/warning.png)
<!-- END STRIP_FOR_RELEASE -->
<!-- END MUNGE: UNVERSIONED_WARNING -->
# Service Accounts
A service account provides an identity for processes that run in a Pod.
*This is a user introduction to Service Accounts. See also the
[Cluster Admin Guide to Service Accounts](../admin/service-accounts-admin.md).*
*Note: This document describes how service accounts behave in a cluster set up
as recommended by the Kubernetes project. Your cluster administrator may have
customized the behavior in your cluster, in which case this documentation may
not apply.*
When you (a human) access the cluster (e.g. using kubectl), you are
authenticated by the apiserver as a particular User Account (currently this is
usually "admin", unless your cluster administrator has customized your
cluster). Processes in containers inside pods can also contact the apiserver.
When they do, they are authenticated as a particular Service Account (e.g.
"default").
## Using the Default Service Account to access the API server.
When you create a pod, you do not need to specify a service account. It is
automatically assigned the `default` service account of the same namespace. If
you get the raw json or yaml for a pod you have created (e.g. `kubectl get
pods/podname -o yaml`), you can see the `spec.serviceAccount` field has been
[automatically set](working-with-resources.md#resources-are-automatically-modified).
You can access the API using a proxy or with a client library, as described in
[Accessing the Cluster](accessing-the-cluster.md#accessing-the-api-from-a-pod).
## Using Multiple Service Accounts
Every namespace has a default service account resource called "default".
You can list this and any other serviceAccount resources in the namespace with this command:
```
kubectl get serviceAccounts
$ NAME SECRETS
default 1
```
You can create additional serviceAccounts like this:
```
$ cat > serviceaccount.yaml <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
name: build-robot
EOF
$ kubectl create -f serviceaccount.json
serviceacccounts/build-robot
```
If you get a complete dump of the service account object, like this:
```
$ kubectl get serviceacccounts/build-robot -o yaml
apiVersion: v1
kind: ServiceAccount
metadata:
creationTimestamp: 2015-06-16T00:12:59Z
name: build-robot
namespace: default
resourceVersion: "272500"
selfLink: /api/v1/namespaces/default/serviceaccounts/build-robot
uid: 721ab723-13bc-11e5-aec2-42010af0021e
secrets:
- name: build-robot-token-bvbk5
```
then you will see that a token has automatically been created and is referenced by the service account.
In the future, you will be able to configure different access policies for each service account.
To use a non-default service account, simply set the `spec.serviceAccount`
field of a pod to the name of the service account you wish to use.
The service account has to exist at the time the pod is created, or it will be rejected.
You cannot update the service account of an already created pod.
You can clean up the service account from this example like this:
```
$ kubectl delete serviceaccount/build-robot
```
<!-- TODO: describe how to create a pod with no Service Account. -->
## Adding Secrets to a service account.
TODO: Test and explain how to use additional non-K8s secrets with an existing service account.
TODO explain:
- The token goes to: "/var/run/secrets/kubernetes.io/serviceaccount/$WHATFILENAME"
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/service-accounts.md?pixel)]()
<!-- END MUNGE: GENERATED_ANALYTICS -->

8
docs/user-guide/working-with-resources.md
View File

@@ -26,7 +26,7 @@ certainly want the docs that go with that version.</h1>
and who want to learn more about using kubectl to manage resources such
as pods and services. Users who want to access the REST API directly,
and developers who want to extend the kubernetes API should
refer to the [api conventions](../api-conventions.md) and
refer to the [api conventions](../devel/api-conventions.md) and
the [api document](../api.md).*
## Resources are Automatically Modified
@@ -58,9 +58,9 @@ The resource we posted had only 9 lines, but the one we got back had 51 lines.
If you `diff original.yaml current.yaml`, you can see the fields added to the pod.
The system adds fields in several ways:
- Some fields are added synchronously with creation of the resource and some are set asynchronously.
- For example: `metadata.uid` is set synchronously. (Read more about [metadata](../api-conventions.md#metadata)).
- For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read mode about [status](../api-conventions.md#spec-and-status) and [late initialization](../api-conventions.md#late-initialization) ).
- Some fields are set to default values. Some defaults vary by cluster and some are fixed for the API at a certain version. (Read more about [defaulting](../api-conventions.md#defaulting)).
- For example: `metadata.uid` is set synchronously. (Read more about [metadata](../devel/api-conventions.md#metadata)).
- For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read mode about [status](../devel/api-conventions.md#spec-and-status) and [late initialization](../devel/api-conventions.md#late-initialization) ).
- Some fields are set to default values. Some defaults vary by cluster and some are fixed for the API at a certain version. (Read more about [defaulting](../devel/api-conventions.md#defaulting)).
- For example, `spec.containers.imagePullPolicy` always defaults to `IfNotPresent` in api v1.
- For example, `spec.containers.resources.limits.cpu` may be defaulted to `100m` on some clusters, to some other value on others, and not defaulted at all on others.
The API will generally not modify fields that you have set; it just sets ones which were unspecified.