whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into logging-sidecar-refactoring-2

Browse Source
This commit is contained in:
Steve Perry
2017-01-25 09:07:11 -08:00
committed by GitHub
parent a2deedd3f5 52c2292dda
commit 5be3af942c
41 changed files with 477 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_data/guides.yml
+1
View File
@@ -8,6 +8,7 @@ toc:
- docs/whatisk8s.md
- docs/getting-started-guides/kubeadm.md
- docs/getting-started-guides/kops.md
- docs/getting-started-guides/kargo.md
- docs/hellonode.md
- docs/getting-started-guides/kubectl.md
- docs/getting-started-guides/binary_release.md
_data/tasks.yml
+1 -1
View File
@@ -1,5 +1,5 @@
bigheader: "Tasks"
abstract: "Step-by-step instructions for performing operations with Kuberentes."
abstract: "Step-by-step instructions for performing operations with Kubernetes."
toc:
- docs/tasks/index.md
docs/admin/authentication.md
+114 -36
View File
@@ -29,9 +29,9 @@ stored as `Secrets`, which are mounted into pods allowing in cluster processes
to talk to the Kubernetes API.
API requests are tied to either a normal user or a service account, or are treated
as anonymous requests. This means every process inside or outside the cluster, from
a human user typing `kubectl` on a workstation, to `kubelets` on nodes, to members
of the control plane, must authenticate when making requests to the API server,
as anonymous requests. This means every process inside or outside the cluster, from
a human user typing `kubectl` on a workstation, to `kubelets` on nodes, to members
of the control plane, must authenticate when making requests to the API server,
or be treated as an anonymous user.
## Authentication strategies
@@ -58,7 +58,7 @@ When multiple are enabled, the first authenticator module
to successfully authenticate the request short-circuits evaluation.
The API server does not guarantee the order authenticators run in.
The `system:authenticated` group is included in the list of groups for all authenticated users.
The `system:authenticated` group is included in the list of groups for all authenticated users.
### X509 Client Certs
@@ -116,10 +116,11 @@ authentication is currently supported for convenience while we finish making the
more secure modes described above easier to use.
The basic auth file format is implemented in `plugin/pkg/auth/authenticator/password/passwordfile/...`
and is a csv file with 3 columns: password, user name, user id.
and is a csv file with a minimum of 3 columns: password, user name, user id, followed by
optional group names. Note, if you have more than one group the column must be double quoted e.g.
```conf
password,user,uid
password,user,uid,"group1,group2,group3"
```
When using basic authentication from an http client, the API server expects an `Authorization` header
@@ -222,44 +223,121 @@ from the OAuth2 [token response](https://openid.net/specs/openid-connect-core-1_
as a bearer token. See [above](#putting-a-bearer-token-in-a-request) for how the token
is included in a request.
To enable the plugin, pass the following required flags:
![Kubernetes OpenID Connect Flow](/images/docs/admin/k8s_oidc_login.svg)
* `--oidc-issuer-url` URL of the provider which allows the API server to discover
public signing keys. Only URLs which use the `https://` scheme are accepted. This is typically
the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".
1. Login to your identity provider
2. Your identity provider will provide you with an `access_token`, `id_token` and a `refresh_token`
3. When using `kubectl`, use your `id_token` with the `--token` flag or add it directly to your `kubeconfig`
4. `kubectl` sends your `id_token` in a header called Authorization to the API server
5. The API server will make sure the JWT signature is valid by checking against the certificate named in the configuration
6. Check to make sure the `id_token` hasn't expired
7. Make sure the user is authorized
8. Once authorized the API server returns a response to `kubectl`
9. `kubectl` provides feedback to the user
* `--oidc-client-id` A client id that all tokens must be issued for.
Since all of the data needed to validate who you are is in the `id_token`, Kubernetes doesn't need to
"phone home" to the identity provider. In a model where every request is stateless this provides a very scalable
solution for authentication. It does offer a few challenges:
1. Kubernetes has no "web interface" to trigger the authentication process. There is no browser or interface to collect credentials which is why you need to authenticate to your identity provider first.
2. The `id_token` can't be revoked, its like a certificate so it should be short-lived (only a few minutes) so it can be very annoying to have to get a new token every few minutes
3. There's no easy way to authenticate to the Kubernetes dashboard without using the `kubectl -proxy` command or a reverse proxy that injects the `id_token`
#### Configuring the API Server
To enable the plugin, configure the following flags on the API server:
| Parameter | Description | Example | Required |
| --------- | ----------- | ------- | ------- |
| --oidc-issuer-url | URL of the provider which allows the API server to discover public signing keys. Only URLs which use the `https://` scheme are accepted. This is typically the provider's discovery URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com". This URL should point to the level below .well-known/openid-configuration | If the discovery URL is https://accounts.google.com/.well-known/openid-configuration the value should be https://accounts.google.com | Yes |
| --oidc-client-id | A client id that all tokens must be issued for. | kubernetes | Yes |
| --oidc-username-claim | JWT claim to use as the user name. By default `sub`, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as `email`, depending on their provider. | sub | No |
| --oidc-groups-claim | JWT claim to use as the user's group. If the claim is present it must be an array of strings. | groups | No |
| --oidc-ca-file | The path to the certificate for the CA that signed your identity provider's web certificate. Defaults to the host's root CAs. | `/etc/kubernetes/ssl/kc-ca.pem` | No |
Importantly, the API server is not an OAuth2 client, rather it can only be
configured to trust a single client. This allows the use of public providers,
configured to trust a single issuer. This allows the use of public providers,
such as Google, without trusting credentials issued to third parties. Admins who
wish utilize multiple OAuth clients should explore providers which support the
wish to utilize multiple OAuth clients should explore providers which support the
`azp` (authorized party) claim, a mechanism for allowing one client to issue
tokens on behalf of another.
The plugin also accepts the following optional flags:
* `--oidc-ca-file` Used by the API server to establish and verify the secure
connection to the issuer. Defaults to the host's root CAs.
And experimental flags:
* `--oidc-username-claim` JWT claim to use as the user name. By default `sub`,
which is expected to be a unique identifier of the end user. Admins can choose
other claims, such as `email`, depending on their provider.
* `--oidc-groups-claim` JWT claim to use as the user's group. If the claim is present
it must be an array of strings.
Kubernetes does not provide an OpenID Connect Identity Provider.
You can use an existing public OpenID Connect Identity Provider (such as Google, or [others](http://connect2id.com/products/nimbus-oauth-openid-connect-sdk/openid-connect-providers)).
Or, you can run your own Identity Provider, such as CoreOS [dex](https://github.com/coreos/dex), [Keycloak](https://github.com/keycloak/keycloak) or CloudFoundry [UAA](https://github.com/cloudfoundry/uaa).
Or, you can run your own Identity Provider, such as CoreOS [dex](https://github.com/coreos/dex), [Keycloak](https://github.com/keycloak/keycloak), CloudFoundry [UAA](https://github.com/cloudfoundry/uaa), or Tremolo Security's [OpenUnison](https://github.com/tremolosecurity/openunison).
The provider needs to support [OpenID connect discovery](https://openid.net/specs/openid-connect-discovery-1_0.html); not all do.
For an identity provider to work with Kubernetes it must:
1. Support [OpenID connect discovery](https://openid.net/specs/openid-connect-discovery-1_0.html); not all do.
2. Run in TLS with non-obsolete ciphers
3. Have a CA signed certificate (even if the CA is not a commercial CA or is self signed)
A note about requirement #3 above, requiring a CA signed certificate. If you deploy your own identity provider (as opposed to one of the cloud providers like Google or Microsoft) you MUST have your identity provider's web server certificate signed by a certificate with the `CA` flag set to `TRUE`, even if it is self signed. This is due to GoLang's TLS client implementation being very strict to the standards around certificate validation. If you don't have a CA handy, you can use this script from the CoreOS team to create a simple CA and a signed certificate and key pair - https://github.com/coreos/dex/blob/1ee5920c54f5926d6468d2607c728b71cfe98092/examples/k8s/gencert.sh or this script based on it that will generate SHA256 certs with a longer life and larger key size https://raw.githubusercontent.com/TremoloSecurity/openunison-qs-kubernetes/master/makecerts.sh.
Setup instructions for specific systems:
- [UAA](http://apigee.com/about/blog/engineering/kubernetes-authentication-enterprise)
- [Dex](https://speakerdeck.com/ericchiang/kubernetes-access-control-with-dex)
- [OpenUnison](https://github.com/TremoloSecurity/openunison-qs-kubernetes)
#### Using kubectl
##### Option 1 - OIDC Authenticator
The first option is to use the `oidc` authenticator. This authenticator takes your `id_token`, `refresh_token` and your OIDC `client_secret` and will refresh your token automatically. Once you have authenticated to your identity provider:
```bash
kubectl config set-credentials USER_NAME \
--auth-provider=oidc
--auth-provider-arg=idp-issuer-url=( issuer url ) \
--auth-provider-arg=client-id=( your client id ) \
--auth-provider-arg=client-secret=( your client secret ) \
--auth-provider-arg=refresh-token=( your refresh token ) \
--auth-provider-arg=idp-certificate-authority=( path to your ca certificate ) \
--auth-provider-arg=id-token=( your id_token )
```
As an example, running the below command after authenticating to your identity provider:
```bash
kubectl config set-credentials mmosley \
--auth-provider=oidc \
--auth-provider-arg=idp-issuer-url=https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP \
--auth-provider-arg=client-id=kubernetes \
--auth-provider-arg=client-secret=1db158f6-177d-4d9c-8a8b-d36869918ec5 \
--auth-provider-arg=refresh-token=q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXqHega4GAXlF+ma+vmYpFcHe5eZR+slBFpZKtQA= \
--auth-provider-arg=idp-certificate-authority=/root/ca.pem \
--auth-provider-arg=id-token=eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw
```
Which would produce the below configuration:
```yaml
users:
- name: mmosley
user:
auth-provider:
config:
client-id: kubernetes
client-secret: 1db158f6-177d-4d9c-8a8b-d36869918ec5
id-token: eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw
idp-certificate-authority: /root/ca.pem
idp-issuer-url: https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP
refresh-token: q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXq
name: oidc
```
Once your `id_token` expires, `kubectl` will attempt to refresh your `id_token` using your `refresh_token` and `client_secret` storing the new values for the `refresh_token` and `id_token` in your `kube/.config`.
##### Option 2 - Use the `--token` Option
The `kubectl` command lets you pass in a token using the `--token` option. Simply copy and paste the `id_token` into this option:
```
kubectl --token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL21sYi50cmVtb2xvLmxhbjo4MDQzL2F1dGgvaWRwL29pZGMiLCJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNDc0NTk2NjY5LCJqdGkiOiI2RDUzNXoxUEpFNjJOR3QxaWVyYm9RIiwiaWF0IjoxNDc0NTk2MzY5LCJuYmYiOjE0NzQ1OTYyNDksInN1YiI6Im13aW5kdSIsInVzZXJfcm9sZSI6WyJ1c2VycyIsIm5ldy1uYW1lc3BhY2Utdmlld2VyIl0sImVtYWlsIjoibXdpbmR1QG5vbW9yZWplZGkuY29tIn0.f2As579n9VNoaKzoF-dOQGmXkFKf1FMyNV0-va_B63jn-_n9LGSCca_6IVMP8pO-Zb4KvRqGyTP0r3HkHxYy5c81AnIh8ijarruczl-TK_yF5akjSTHFZD-0gRzlevBDiH8Q79NAr-ky0P4iIXS8lY9Vnjch5MF74Zx0c3alKJHJUnnpjIACByfF2SCaYzbWFMUNat-K1PaUk5-ujMBG7yYnr95xD-63n8CO8teGUAAEMx6zRjzfhnhbzX-ajwZLGwGUBT4WqjMs70-6a7_8gZmLZb2az1cZynkFRj2BaCkVT3A2RrjeEwZEtGXlMqKJ1_I2ulrOVsYx01_yD35-rw get nodes
```
### Webhook Token Authentication
@@ -369,12 +447,12 @@ HTTP status codes can be used to supply additional error context.
The API server can be configured to identify users from request header values, such as `X-Remote-User`.
It is designed for use in combination with an authenticating proxy, which sets the request header value.
In order to prevent header spoofing, the authenticating proxy is required to present a valid client
certificate to the API server for validation against the specified CA before the request headers are
certificate to the API server for validation against the specified CA before the request headers are
checked.
* `--requestheader-username-headers` Required, case-insensitive. Header names to check, in order, for the user identity. The first header containing a value is used as the identity.
* `--requestheader-client-ca-file` Required. PEM-encoded certificate bundle. A valid client certificate must be presented and validated against the certificate authorities in the specified file before the request headers are checked for user names.
* `--requestheader-allowed-names` Optional. List of common names (cn). If set, a valid client certificate with a Common Name (cn) in the specified list must be presented before the request headers are checked for user names. If empty, any Common Name is allowed.
* `--requestheader-allowed-names` Optional. List of common names (cn). If set, a valid client certificate with a Common Name (cn) in the specified list must be presented before the request headers are checked for user names. If empty, any Common Name is allowed.
### Keystone Password
@@ -402,18 +480,18 @@ changes](https://github.com/kubernetes/kubernetes/pull/25536) for more details.
## Anonymous requests
Anonymous access is enabled by default, and can be disabled by passing `--anonymous-auth=false`
Anonymous access is enabled by default, and can be disabled by passing `--anonymous-auth=false`
option to the API server during startup.
When enabled, requests that are not rejected by other configured authentication methods are
treated as anonymous requests, and given a username of `system:anonymous` and a group of
When enabled, requests that are not rejected by other configured authentication methods are
treated as anonymous requests, and given a username of `system:anonymous` and a group of
`system:unauthenticated`.
For example, on a server with token authentication configured, and anonymous access enabled,
a request providing an invalid bearer token would receive a `401 Unauthorized` error.
A request providing no bearer token would be treated as an anonymous request.
a request providing an invalid bearer token would receive a `401 Unauthorized` error.
A request providing no bearer token would be treated as an anonymous request.
If you rely on authentication alone to authorize access, either change to use an
If you rely on authentication alone to authorize access, either change to use an
authorization mode other than `AlwaysAllow`, or set `--anonymous-auth=false`.
## Plugin Development
docs/admin/cluster-large.md
+3 -3
View File
@@ -99,13 +99,13 @@ To avoid running into cluster addon resource issues, when creating a cluster wit
* Scale memory and CPU limits for each of the following addons, if used, as you scale up the size of cluster (there is one replica of each handling the entire cluster so memory and CPU usage tends to grow proportionally with size/load on cluster):
* [InfluxDB and Grafana](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/cluster-monitoring/influxdb/influxdb-grafana-controller.yaml)
* [skydns, kube2sky, and dns etcd](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/skydns-rc.yaml.in)
* [kubedns, dnsmasq, and sidecar](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/kubedns-controller.yaml.in)
* [Kibana](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-elasticsearch/kibana-controller.yaml)
* Scale number of replicas for the following addons, if used, along with the size of cluster (there are multiple replicas of each so increasing replicas should help handle increased load, but, since load per replica also increases slightly, also consider increasing CPU/memory limits):
* [elasticsearch](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-elasticsearch/es-controller.yaml)
* Increase memory and CPU limits slightly for each of the following addons, if used, along with the size of cluster (there is one replica per node but CPU/memory usage increases slightly along with cluster load/size as well):
* [FluentD with ElasticSearch Plugin](http://releases.k8s.io/{{page.githubbranch}}/cluster/saltbase/salt/fluentd-es/fluentd-es.yaml)
* [FluentD with GCP Plugin](http://releases.k8s.io/{{page.githubbranch}}/cluster/saltbase/salt/fluentd-gcp/fluentd-gcp.yaml)
* [FluentD with ElasticSearch Plugin](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-elasticsearch/fluentd-es-ds.yaml)
* [FluentD with GCP Plugin](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/fluentd-gcp/fluentd-gcp-ds.yaml)
Heapster's resource limits are set dynamically based on the initial size of your cluster (see [#16185](http://issue.k8s.io/16185)
and [#22940](http://issue.k8s.io/22940)). If you find that Heapster is running
docs/admin/cluster-management.md
+4 -4
View File
@@ -159,11 +159,11 @@ node discovery; currently this is only Google Compute Engine, not including Core
### Upgrading to a different API version
When a new API version is released, you may need to upgrade a cluster to support the new API version (e.g. switching from 'v1' to 'v2' when 'v2' is launched)
When a new API version is released, you may need to upgrade a cluster to support the new API version (e.g. switching from 'v1' to 'v2' when 'v2' is launched).
This is an infrequent event, but it requires careful management. There is a sequence of steps to upgrade to a new API version.
1. Turn on the new api version.
1. Turn on the new API version.
1. Upgrade the cluster's storage to use the new version.
1. Upgrade all config files. Identify users of the old API version endpoints.
1. Update existing objects in the storage to new version by running `cluster/update-storage-objects.sh`.
@@ -171,9 +171,9 @@ This is an infrequent event, but it requires careful management. There is a sequ
### Turn on or off an API version for your cluster
Specific API versions can be turned on or off by passing --runtime-config=api/<version> flag while bringing up the API server. For example: to turn off v1 API, pass `--runtime-config=api/v1=false`.
Specific API versions can be turned on or off by passing `--runtime-config=api/<version>` flag while bringing up the API server. For example: to turn off v1 API, pass `--runtime-config=api/v1=false`.
runtime-config also supports 2 special keys: api/all and api/legacy to control all and legacy APIs respectively.
For example, for turning off all api versions except v1, pass `--runtime-config=api/all=false,api/v1=true`.
For example, for turning off all API versions except v1, pass `--runtime-config=api/all=false,api/v1=true`.
For the purposes of these flags, _legacy_ APIs are those APIs which have been explicitly deprecated (e.g. `v1beta3`).
### Switching your cluster's storage API version
docs/admin/federation/index.md
+2 -2
View File
@@ -236,7 +236,7 @@ metadata:
name: kube-dns
namespace: kube-system
data:
federations: <federation-name>=<dns-domain-name>
federations: <federation-name>=<federation-domain-name>
```
where `<federation-name>` should be replaced by the name you want to give to your
@@ -249,7 +249,7 @@ http://kubernetes.io/docs/user-guide/configmap/.
### Kubernetes 1.4 and earlier: Setting federations flag on kube-dns-rc
If your cluster is running Kubernetes version 1.4 or earlier, you must to restart
If your cluster is running Kubernetes version 1.4 or earlier, you must restart
KubeDNS and pass it a `--federations` flag, which tells it about valid federation DNS hostnames.
The flag uses the following format:
docs/admin/ha-master-gce.md
+2 -2
View File
@@ -84,7 +84,7 @@ The following sample commands demonstrate this process:
$ KUBE_DELETE_NODES=false KUBE_GCE_ZONE=replica_zone KUBE_REPLICA_NAME=replica_name ./cluster/kube-down.sh
```
2. Add a new replica in place of the old one:
<ol start="2"><li>Add a new replica in place of the old one:</li></ol>
```shell
$ KUBE_GCE_ZONE=replica-zone KUBE_REPLICATE_EXISTING_MASTER=true ./cluster/kube-up.sh
@@ -102,7 +102,7 @@ A two-replica cluster is thus inferior, in terms of HA, to a single replica clus
* When you add a master replica, cluster state (etcd) is copied to a new instance.
If the cluster is large, it may take a long time to duplicate its state.
This operation may be speed up by migrating etcd data directory, as described [here](https://coreos.com/etcd/docs/latest/admin_guide.html#member-migration) here
This operation may be sped up by migrating etcd data directory, as described [here](https://coreos.com/etcd/docs/latest/admin_guide.html#member-migration)
(we are considering adding support for etcd data dir migration in future).
## Implementation notes
docs/admin/limitrange/index.md
+4 -4
View File
@@ -23,7 +23,7 @@ to 512MB of memory. The cluster operator creates a separate namespace for each
each namespace.
3. Users may create a pod which consumes resources just below the capacity of a machine. The left over space
may be too small to be useful, but big enough for the waste to be costly over the entire cluster. As a result,
the cluster operator may want to set limits that a pod must consume at least 20% of the memory and cpu of their
the cluster operator may want to set limits that a pod must consume at least 20% of the memory and CPU of their
average node size in order to provide for more uniform scheduling and to limit waste.
This example demonstrates how limits can be applied to a Kubernetes [namespace](/docs/admin/namespaces/walkthrough/) to control
@@ -101,7 +101,7 @@ The limits enumerated in a namespace are only enforced when a pod is created or
the cluster. If you change the limits to a different value range, it does not affect pods that
were previously created in a namespace.
If a resource (cpu or memory) is being restricted by a limit, the user will get an error at time
If a resource (CPU or memory) is being restricted by a limit, the user will get an error at time
of creation explaining why.
Let's first spin up a [Deployment](/docs/user-guide/deployments) that creates a single container Pod to demonstrate
@@ -145,9 +145,9 @@ spec:
volumeMounts:
```
Note that our nginx container has picked up the namespace default cpu and memory resource *limits* and *requests*.
Note that our nginx container has picked up the namespace default CPU and memory resource *limits* and *requests*.
Let's create a pod that exceeds our allowed limits by having it have a container that requests 3 cpu cores.
Let's create a pod that exceeds our allowed limits by having it have a container that requests 3 CPU cores.
```shell
$ kubectl create -f docs/admin/limitrange/invalid-pod.yaml --namespace=limit-example
docs/admin/master-node-communication.md
+1 -1
View File
@@ -91,7 +91,7 @@ HTTP connections and are therefore neither authenticated nor encrypted. They
can be run over a secure HTTPS connection by prefixing `https:` to the node,
pod, or service name in the API URL, but they will not validate the certificate
provided by the HTTPS endpoint nor provide client credentials so while the
connection will by encrypted, it will not provide any guarantees of integrity.
connection will be encrypted, it will not provide any guarantees of integrity.
These connections **are not currently safe** to run over untrusted and/or
public networks.
docs/admin/multiple-zones.md
+10 -7
View File
@@ -51,7 +51,7 @@ admission controller automatically adds zone labels to them. The scheduler (via
`VolumeZonePredicate` predicate) will then ensure that pods that claim a
given volume are only placed into the same zone as that volume, as volumes
cannot be attached across zones.
## Limitations
There are some important limitations of the multizone support:
@@ -158,8 +158,7 @@ kubernetes-minion-wf8i Ready 2m beta.kubernetes.io
### Volume affinity
Create a volume (only PersistentVolumes are supported for zone
affinity), using the new dynamic volume creation:
Create a volume using the dynamic volume creation (only PersistentVolumes are supported for zone affinity):
```json
kubectl create -f - <<EOF
@@ -186,10 +185,14 @@ kubectl create -f - <<EOF
EOF
```
The PV is also labeled with the zone & region it was created in. For
version 1.2, dynamic persistent volumes are always created in the zone
of the cluster master (here us-central1-a / us-west-2a); this will
be improved in a future version (issue [#23330](https://github.com/kubernetes/kubernetes/issues/23330).)
**NOTE:** For version 1.3+ Kubernetes will distribute dynamic PV claims across
the configured zones. For version 1.2, dynamic persistent volumes were
always created in the zone of the cluster master
(here us-central1-a / us-west-2a); that issue
([#23330](https://github.com/kubernetes/kubernetes/issues/23330))
was addressed in 1.3+.
Now lets validate that Kubernetes automatically labeled the zone & region the PV was created in.
```shell
> kubectl get pv --show-labels
docs/admin/namespaces/index.md
+1
View File
@@ -87,6 +87,7 @@ a *Namespace*.
See [Admission control: Limit Range](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/admission_control_limit_range.md)
A namespace can be in one of two phases:
* `Active` the namespace is in use
* `Terminating` the namespace is being deleted, and can not be used for new objects
docs/admin/namespaces/walkthrough.md
+1 -1
View File
@@ -63,7 +63,7 @@ Create the development namespace using kubectl.
$ kubectl create -f docs/admin/namespaces/namespace-dev.json
```
And then lets create the production namespace using kubectl.
And then let's create the production namespace using kubectl.
```shell
$ kubectl create -f docs/admin/namespaces/namespace-prod.json
docs/admin/static-pods.md
+28 -28
View File
@@ -22,45 +22,45 @@ For example, this is how to start a simple web server as a static pod:
1. Choose a node where we want to run the static pod. In this example, it's `my-node1`.
```shell
[joe@host ~] $ ssh my-node1
```
```shell
[joe@host ~] $ ssh my-node1
```
2. Choose a directory, say `/etc/kubelet.d` and place a web server pod definition there, e.g. `/etc/kubernetes.d/static-web.yaml`:
```shell
[root@my-node1 ~] $ mkdir /etc/kubernetes.d/
[root@my-node1 ~] $ cat <<EOF >/etc/kubernetes.d/static-web.yaml
apiVersion: v1
kind: Pod
metadata:
name: static-web
labels:
role: myrole
spec:
containers:
```shell
[root@my-node1 ~] $ mkdir /etc/kubernetes.d/
[root@my-node1 ~] $ cat <<EOF >/etc/kubernetes.d/static-web.yaml
apiVersion: v1
kind: Pod
metadata:
name: static-web
labels:
role: myrole
spec:
containers:
- name: web
image: nginx
ports:
- name: web
image: nginx
ports:
- name: web
containerPort: 80
protocol: tcp
EOF
```
containerPort: 80
protocol: TCP
EOF
```
2. Configure your kubelet daemon on the node to use this directory by running it with `--pod-manifest-path=/etc/kubelet.d/` argument. On Fedora edit `/etc/kubernetes/kubelet` to include this line:
```conf
KUBELET_ARGS="--cluster-dns=10.254.0.10 --cluster-domain=kube.local --pod-manifest-path=/etc/kubelet.d/"
```
```conf
KUBELET_ARGS="--cluster-dns=10.254.0.10 --cluster-domain=kube.local --pod-manifest-path=/etc/kubelet.d/"
```
Instructions for other distributions or Kubernetes installations may vary.
Instructions for other distributions or Kubernetes installations may vary.
3. Restart kubelet. On Fedora, this is:
```shell
[root@my-node1 ~] $ systemctl restart kubelet
```
```shell
[root@my-node1 ~] $ systemctl restart kubelet
```
## Pods created via HTTP
docs/concepts/abstractions/controllers/statefulsets.md
+1 -1
View File
@@ -42,7 +42,7 @@ provides a set of stateless replicas. Controllers such as
## Limitations
* StatefulSet is a beta resource, not available in any Kubernetes release prior to 1.5.
* As with all alpha/beta resources, you can disable StatefulSet through the `--runtime-config` option passed to the apiserver.
* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin.
* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin.
* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the StatefulSet. This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources.
* StatefulSets currently require a [Headless Service](/docs/user-guide/services/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service.
* Updating an existing StatefulSet is currently a manual process.
docs/getting-started-guides/kargo.md
+104
View File
@@ -0,0 +1,104 @@
---
title: Installing Kubernetes On-premise/Cloud Providers with Kargo
---
<style>
li>.highlighter-rouge {position:relative; top:3px;}
</style>
## Overview
This quickstart helps to install a Kubernetes cluster hosted
on GCE, Azure, OpenStack, AWS or Baremetal with
[`Kargo`](https://github.com/kubernetes-incubator/kargo) tool.
Kargo is a composition of [Ansible](http://docs.ansible.com/) playbooks,
[inventory](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ansible.md)
generation CLI tools and domain knowledge for generic OS/Kubernetes
clusters configuration management tasks. It provides:
* [High available cluster](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ha-mode.md)
* [Composable](https://github.com/kubernetes-incubator/kargo/blob/master/docs/vars.md)
(Choice of the network plugin, for instance)
* Support most popular Linux
[distributions](https://github.com/kubernetes-incubator/kargo#supported-linux-distributions)
* Continuous integration tests
To choose a tool which fits your use case the best, you may want to read this
[comparison](https://github.com/kubernetes-incubator/kargo/blob/master/docs/comparisons.md)
to [kubeadm](../kubeadm) and [kops](../kops).
## Creating a cluster
### (1/4) Ensure the underlay [requirements](https://github.com/kubernetes-incubator/kargo#requirements) are met
#### Checklist
* You must have cloud instances or baremetal nodes running for your future Kubernetes cluster.
A way to achieve that is to use the
[kargo-cli tool](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md).
* Or provision baremetal hosts with a tool-of-your-choice or launch cloud instances,
then create an inventory file for Ansible with this [tool](https://github.com/kubernetes-incubator/kargo/blob/master/contrib/inventory_generator/inventory_generator.py).
### (2/4) Compose the deployment
#### Checklist
* Customize your deployment by usual Ansible meanings, which is
[generating inventory](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md#building-your-own-inventory)
and overriding default data [variables](https://github.com/kubernetes-incubator/kargo/blob/master/docs/vars.md).
Or just stick with default values (Kargo will choose Flannel networking plugin for you
then). This includes steps like deciding on the:
* DNS [configuration options](https://github.com/kubernetes-incubator/kargo/blob/master/docs/dns-stack.md)
* [Networking plugin](https://github.com/kubernetes-incubator/kargo#network-plugins) to use
* [Versions](https://github.com/kubernetes-incubator/kargo#versions-of-supported-components)
of components.
* Additional node groups like [bastion hosts](https://github.com/kubernetes-incubator/kargo/blob/master/docs/ansible.md#bastion-host) or
[Calico BGP route reflectors](https://github.com/kubernetes-incubator/kargo/blob/master/docs/calico.md#optional--bgp-peering-with-border-routers).
* Plan custom deployment steps, if any, or use the default composition layer in the
[cluster definition file](https://github.com/kubernetes-incubator/kargo/blob/master/cluster.yml).
Taking the best from Ansible world, Kargo allows users to execute arbitrary steps via the
``ansible-playbook`` with given inventory, playbooks, data overrides and tags, limits, batches
of nodes to deploy and so on.
* For large deployments (100+ nodes), you may want to
[tweak things](https://github.com/kubernetes-incubator/kargo/blob/master/docs/large-deployments.md)
for best results.
### (3/4) Run the deployment
#### Checklist
* Apply deployment with
[kargo-cli tool](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md)
or ``ansible-playbook``
[manual commands](https://github.com/kubernetes-incubator/kargo/blob/master/docs/getting-started.md#starting-custom-deployment).
### (4/4) (Optional) verify inter-pods connectivity and DNS resolve with [Netchecker](https://github.com/kubernetes-incubator/kargo/blob/master/docs/netcheck.md)
#### Checklist
* Enusre the netchecker-agent's pods can resolve DNS requests and ping each over within the default namespace.
Those pods mimic similar behavior of the rest of the workloads and serve as cluster health indicators.
## Explore contributed add-ons
See the [list of contributed playbooks](https://github.com/kubernetes-incubator/kargo/tree/master/contrib)
to explore other deployment options.
## What's next
Kargo has quite a few [marks on the radar](https://github.com/kubernetes-incubator/kargo/blob/master/docs/roadmap.md).
## Cleanup
To delete your scratch cluster, you can apply the
[reset role](https://github.com/kubernetes-incubator/kargo/blob/master/roles/reset/tasks/main.yml)
with the manual ``ansible-playbook`` command.
Note, that it is highly unrecommended to delete production clusters with the reset playbook!
## Feedback
* Slack Channel: [#kargo](https://kubernetes.slack.com/messages/kargo/)
* [GitHub Issues](https://github.com/kubernetes-incubator/kargo/issues)
docs/getting-started-guides/minikube.md
+5 -17
View File
@@ -1,8 +1,8 @@
---
assignees:
- dlorenc
- janetkuo
- jlowdermilk
- r2d4
- aaron-prindle
title: Running Kubernetes Locally via Minikube
---
@@ -31,19 +31,7 @@ Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs a
* Linux
* [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or [KVM](http://www.linux-kvm.org/) installation,
* VT-x/AMD-v virtualization must be enabled in BIOS
* `kubectl` must be on your path. To install kubectl:
**Kubectl for Linux/amd64**
```
curl -Lo kubectl http://storage.googleapis.com/kubernetes-release/release/{{page.version}}/bin/linux/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
```
**Kubectl for OS X/amd64**
```
curl -Lo kubectl http://storage.googleapis.com/kubernetes-release/release/{{page.version}}/bin/darwin/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
```
* `kubectl` See the [kubectl installation instructions](/docs/getting-started-guides/kubectl/) for more details.
### Instructions
@@ -175,7 +163,7 @@ This flag is repeated, so you can pass it several times with several different v
This flag takes a string of the form `component.key=value`, where `component` is one of the strings from the above list, `key` is a value on the
configuration struct and `value` is the value to set.
Valid `key`s can be found by examining the documentation for the Kubernetes `componentconfigs` for each component.
Valid `key`s can be found by examining the documentation for the Kubernetes `componentconfigs` for each component.
Here is the documentation for each supported configuration:
* [kubelet](https://godoc.org/k8s.io/kubernetes/pkg/apis/componentconfig#KubeletConfiguration)
@@ -191,7 +179,7 @@ To change the `MaxPods` setting to 5 on the Kubelet, pass this flag: `--extra-co
This feature also supports nested structs. To change the `LeaderElection.LeaderElect` setting to `true` on the scheduler, pass this flag: `--extra-config=scheduler.LeaderElection.LeaderElect=true`.
To set the `AuthorizationMode` on the `apiserver` to `RBAC`, you can use: `--extra-config=apiserver.AuthorizationMode=RBAC`.
To set the `AuthorizationMode` on the `apiserver` to `RBAC`, you can use: `--extra-config=apiserver.AuthorizationMode=RBAC`.
### Stopping a Cluster
The [minikube stop](https://github.com/kubernetes/minikube/blob/master/docs/minikube_stop.md) command can be used to stop your cluster.
docs/getting-started-guides/scratch.md
+3 -5
View File
@@ -405,7 +405,7 @@ Arguments to consider:
- `--cluster-domain=` to the dns domain prefix to use for cluster DNS addresses.
- `--docker-root=`
- `--root-dir=`
- `--configure-cbr0=` (described above)
- `--configure-cbr0=` (described below)
- `--register-node` (described in [Node](/docs/admin/node) documentation.)
### kube-proxy
@@ -774,10 +774,8 @@ Template for controller manager pod:
Flags to consider using with controller manager:
- `--cluster-name=$CLUSTER_NAME`
- `--cluster-cidr=`
- *TODO*: explain this flag.
- `--allocate-node-cidrs=`
- *TODO*: explain when you want controller to do this and when you want to do it another way.
- `--cluster-cidr=`, the CIDR range for pods in cluster.
- `--allocate-node-cidrs=`, if you are using `--cloud-provider=`, allocate and set the CIDRs for pods on the cloud provider.
- `--cloud-provider=` and `--cloud-config` as described in apiserver section.
- `--service-account-private-key-file=/srv/kubernetes/server.key`, used by the [service account](/docs/user-guide/service-accounts) feature.
- `--master=127.0.0.1:8080`
docs/getting-started-guides/ubuntu/index.md
+18 -2
View File
@@ -9,11 +9,27 @@ There are multiple ways to run a Kubernetes cluster with Ubuntu. These pages exp
{% capture body %}
## Official Ubuntu Guides
- [The Canonical Distribution of Kubernetes](/docs/getting-started-guides/ubuntu)
- [The Canonical Distribution of Kubernetes](https://www.ubuntu.com/cloud/kubernetes)
Supports AWS, GCE, Azure, Joyent, OpenStack, Bare Metal and local workstation deployment.
### Operational Guides
### Quick Start
[conjure-up](http://conjure-up.io/) provides quick wasy to deploy Kubernetes on multiple clouds and bare metal. It provides a user-friendly UI that prompts you for cloud credentials and configuration options:
Available for Ubuntu 16.04 and newer:
```
sudo apt-add-repository ppa:juju/stable
sudo apt-add-repository ppa:conjure-up/next
sudo apt update
sudo apt install conjure-up
conjure-up
```
### Operational Guides
These are more in-depth guides for users choosing to run Kubernetes in production:
- [Installation](/docs/getting-started-guides/ubuntu/installation)
- [Validation](/docs/getting-started-guides/ubuntu/validation)
docs/getting-started-guides/ubuntu/installation.md
+2 -1
View File
@@ -38,7 +38,8 @@ so we can find them.
- OpenStack deployments are currently only tested on Icehouse and newer.
- Network access to the following domains
- *.jujucharms.com
- gcr.io
- gcr.io
- github.com
- Access to an Ubuntu mirror (public or private)
docs/getting-started-guides/ubuntu/networking.md
+2 -2
View File
@@ -9,7 +9,7 @@ This page shows how to the various network portions of a cluster work, and how t
This page assumes you have a working Juju deployed cluster.
{% endcapture %}
Kubernetes supports the [Container Network Interface (CNI)]](https://github.com/containernetworking/cni).
Kubernetes supports the [Container Network Interface (CNI)](https://github.com/containernetworking/cni).
This is a network plugin architecture that allows you to use whatever
Kubernetes-friendly SDN you want. Currently this means support for Flannel.
@@ -50,4 +50,4 @@ how large your cluster will potentially scale. Class A IP ranges with /24 are
a good option.
{% endcapture %}
{% include templates/task.md %}
{% include templates/task.md %}
docs/getting-started-guides/vsphere.md
+1 -1
View File
@@ -79,7 +79,7 @@ Sample Config:
#### Known issues
* [Volumes are not removed from a VM configuration if the VM is down](https://github.com/kubernetes/kubernetes/issues/33061). The workaround is to manually remove the disk from VM settings before powering it up.
* [FS groups are not supported in 1.4.7](https://github.com/kubernetes/kubernetes/issues/34039)
* [FS groups are not supported in 1.4.7](https://github.com/kubernetes/kubernetes/issues/34039) - This issue is fixed in 1.4.8
### Kube-up (Deprecated)
docs/index.md
+1
View File
@@ -20,6 +20,7 @@ title: Kubernetes Documentation
<li><a href="/docs/getting-started-guides/minikube/">Minikube</a>: Install a single-node Kubernetes cluster on your local machine for development and testing.</li>
<li><a href="/docs/getting-started-guides/kops/">Installing Kubernetes on AWS with kops</a>: Bring up a complete Kubernetes cluster on Amazon Web Services, using a tool called <code>kops</code>.</li>
<li><a href="/docs/getting-started-guides/kubeadm/">Installing Kubernetes on Linux with kubeadm</a> (Alpha): Install a secure Kubernetes cluster on any pre-existing machines running Linux, using the built-in <code>kubeadm</code> tool.</li>
<li><a href="/docs/getting-started-guides/kargo/">Installing Kubernetes On-premise/Cloud Providers with Kargo</a>: Deploy a Kubernetes cluster on-premise baremetal or hosted on cloud providers, with Ansible and <code>kargo</code> tools.</li>
</ul>
<h2>Guides, Tutorials, Tasks, and Concepts</h2>
docs/tasks/index.md
+1 -1
View File
@@ -24,7 +24,7 @@ single thing, typically by giving a short sequence of steps.
* [Distributing Credentials Securely](/docs/tasks/configure-pod-container/distribute-credentials-secure/)
* [Pulling an Image from a Private Registry](/docs/tasks/configure-pod-container/pull-image-private-registry/)
* [Configuring Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
* [Communicating Between Pods Running in the Same Container](/docs/tasks/configure-pod-container/communicate-containers-same-pod/)
* [Communicating Between Containers Running in the Same Pod](/docs/tasks/configure-pod-container/communicate-containers-same-pod/)
* [Configuring Pod Initialization](/docs/tasks/configure-pod-container/configure-pod-initialization/)
* [Attaching Handlers to Container Lifecycle Events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/)
docs/tutorials/stateful-application/mysql-statefulset.yaml
+3 -4
View File
@@ -16,8 +16,6 @@ spec:
"image": "mysql:5.7",
"command": ["bash", "-c", "
set -ex\n
# mysqld --initialize expects an empty data dir.\n
rm -rf /mnt/data/lost+found\n
# Generate mysql server-id from pod ordinal index.\n
[[ `hostname` =~ -([0-9]+)$ ]] || exit 1\n
ordinal=${BASH_REMATCH[1]}\n
@@ -32,7 +30,6 @@ spec:
fi\n
"],
"volumeMounts": [
{"name": "data", "mountPath": "/mnt/data"},
{"name": "conf", "mountPath": "/mnt/conf.d"},
{"name": "config-map", "mountPath": "/mnt/config-map"}
]
@@ -54,7 +51,7 @@ spec:
xtrabackup --prepare --target-dir=/var/lib/mysql\n
"],
"volumeMounts": [
{"name": "data", "mountPath": "/var/lib/mysql"},
{"name": "data", "mountPath": "/var/lib/mysql", "subPath": "mysql"},
{"name": "conf", "mountPath": "/etc/mysql/conf.d"}
]
}
@@ -72,6 +69,7 @@ spec:
volumeMounts:
- name: data
mountPath: /var/lib/mysql
subPath: mysql
- name: conf
mountPath: /etc/mysql/conf.d
resources:
@@ -140,6 +138,7 @@ spec:
volumeMounts:
- name: data
mountPath: /var/lib/mysql
subPath: mysql
- name: conf
mountPath: /etc/mysql/conf.d
resources:
docs/tutorials/stateful-application/zookeeper.md
+1 -1
View File
@@ -26,7 +26,7 @@ Kubernetes concepts.
* [Cluster DNS](/docs/admin/dns/)
* [Headless Services](/docs/user-guide/services/#headless-services)
* [PersistentVolumes](/docs/user-guide/volumes/)
* [PersistentVolume Provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/)
* [PersistentVolume Provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/)
* [ConfigMaps](/docs/user-guide/configmap/)
* [StatefulSets](/docs/concepts/abstractions/controllers/statefulsets/)
* [PodDisruptionBudgets](/docs/admin/disruptions/#specifying-a-poddisruptionbudget)
docs/user-guide/compute-resources.md
+5 -6
View File
@@ -122,17 +122,16 @@ runner (Docker or rkt).
When using Docker:
- The `spec.containers[].resources.requests.cpu` is converted to its core value (potentially fractional),
and multiplied by 1024, and used as the value of the [`--cpu-shares`](
https://docs.docker.com/reference/run/#runtime-constraints-on-resources) flag to the `docker run`
command.
and multiplied by 1024, and used as the value of the [`--cpu-shares`](https://docs.docker.com/engine/reference/run/#/cpu-share-constraint)
flag to the `docker run` command.
- The `spec.containers[].resources.limits.cpu` is converted to its millicore value,
multiplied by 100000, and then divided by 1000, and used as the value of the [`--cpu-quota`](
https://docs.docker.com/reference/run/#runtime-constraints-on-resources) flag to the `docker run`
https://docs.docker.com/engine/reference/run/#/cpu-quota-constraint) flag to the `docker run`
command. The [`--cpu-period`] flag is set to 100000 which represents the default 100ms period
for measuring quota usage. The kubelet enforces cpu limits if it was started with the
[`--cpu-cfs-quota`] flag set to true. As of version 1.2, this flag will now default to true.
- The `spec.containers[].resources.limits.memory` is converted to an integer, and used as the value
of the [`--memory`](https://docs.docker.com/reference/run/#runtime-constraints-on-resources) flag
of the [`--memory`](https://docs.docker.com/engine/reference/run/#/user-memory-constraints) flag
to the `docker run` command.
**TODO: document behavior for rkt**
@@ -362,7 +361,7 @@ such as [EmptyDir volumes](/docs/user-guide/volumes/#emptydir).
The current system only supports container requests and limits for CPU and Memory.
It is planned to add new resource types, including a node disk space
resource, and a framework for adding custom [resource types](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/resources.md#resource-types).
resource, and a framework for adding custom [resource types](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/resources.md).
Kubernetes supports overcommitment of resources by supporting multiple levels of [Quality of Service](http://issue.k8s.io/168).
docs/user-guide/configmap/index.md
+64 -3
View File
@@ -291,6 +291,34 @@ SPECIAL_LEVEL_KEY=very
SPECIAL_TYPE_KEY=charm
```
#### Optional ConfigMap in environment variables
There might be situations where environment variables are not
always required. These environment variables can be marked as optional in a
pod like so:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "-c", "env" ]
env:
- name: SPECIAL_LEVEL_KEY
valueFrom:
configMapKeyRef:
name: a-config
key: akey
optional: true
restartPolicy: Never
```
When this pod is run, the output will be empty.
### Use-Case: Set command-line arguments with ConfigMap
ConfigMaps can also be used to set the value of the command or arguments in a container. This is
@@ -422,6 +450,38 @@ very
You can project keys to specific paths and specific permissions on a per-file
basis. The [Secrets](/docs/user-guide/secrets/) user guide explains the syntax.
#### Optional ConfigMap via volume plugin
Volumes and files provided by a ConfigMap can be also be marked as optional.
The ConfigMap or the key specified does not have to exist. The mount path for
such items will always be created.
```yaml
apiVersion: v1
kind: Pod
metadata:
name: dapi-test-pod
spec:
containers:
- name: test-container
image: gcr.io/google_containers/busybox
command: [ "/bin/sh", "-c", "ls /etc/config" ]
volumeMounts:
- name: config-volume
mountPath: /etc/config
volumes:
- name: config-volume
configMap:
name: no-config
optional: true
restartPolicy: Never
```
When this pod is run, the output will be:
```shell
```
## Real World Example: Configuring Redis
Let's take a look at a real-world example: configuring redis using ConfigMap. Say we want to inject
@@ -517,9 +577,10 @@ $ kubectl exec -it redis redis-cli
## Restrictions
ConfigMaps must be created before they are consumed in pods. Controllers may be written to tolerate
missing configuration data; consult individual components configured via ConfigMap on a case-by-case
basis.
ConfigMaps must be created before they are consumed in pods unless they are
marked as optional. Controllers may be written to tolerate missing
configuration data; consult individual components configured via ConfigMap on
a case-by-case basis.
ConfigMaps reside in a namespace. They can only be referenced by pods in the same namespace.
docs/user-guide/environment-guide/index.md
+1 -1
View File
@@ -79,7 +79,7 @@ First the frontend pod's information is printed. The pod name and
[namespace](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md) are retrieved from the
[Downward API](/docs/user-guide/downward-api). Next, `USER_VAR` is the name of
an environment variable set in the [pod
definition](/docs/user-guide/environment-guide/show-rc.yaml). Then, the dynamic Kubernetes environment
definition](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/user-guide/environment-guide/show-rc.yaml). Then, the dynamic Kubernetes environment
variables are scanned and printed. These are used to find the backend
service, named `backend-srv`. Finally, the frontend pod queries the
backend service and prints the information returned. Again the backend
docs/user-guide/federation/index.md
+3 -1
View File
@@ -37,13 +37,15 @@ Once we have the control plane setup, we can start creating federation API
resources.
The following guides explain some of the resources in detail:
* [ConfigMap](/docs/user-guide/federation/configmap/)
* [DaemonSets](/docs/user-guide/federation/daemonsets/)
* [Deployment](/docs/user-guide/federation/deployment/)
* [Events](/docs/user-guide/federation/events/)
* [Ingress](/docs/user-guide/federation/federated-ingress/)
* [Namespaces](/docs/user-guide/federation/namespaces/)
* [ReplicaSets](/docs/user-guide/federation/replicasets/)
* [Secrets](/docs/user-guide/federation/secrets/)
* [Services](/docs/user-guide/federation/federated-services/)
<!-- TODO: Add more guides here -->
[API reference docs](/docs/federation/api-reference/) lists all the
resources supported by federation apiserver.
docs/user-guide/garbage-collection.md
+1 -1
View File
@@ -27,7 +27,7 @@ You can set up owner-dependent relationships among other objects by manually set
When deleting an object, you can request the GC to ***asynchronously*** delete its dependents by ***explicitly*** specifying `deleteOptions.orphanDependents=false` in the deletion request that you send to the API server. A 200 OK response from the API server indicates the owner is deleted.
In Kubernetes version 1.5, synchronous garbage collection is under active development. See the [tracking [issue](https://github.com/kubernetes/kubernetes/issues/29891) for more details.
In Kubernetes version 1.5, synchronous garbage collection is under active development. See the tracking [issue](https://github.com/kubernetes/kubernetes/issues/29891) for more details.
If you specify `deleteOptions.orphanDependents=true`, or leave it blank, then the GC will first reset the `ownerReferences` in the dependents, then delete the owner. Note that the deletion of the owner object is asynchronous, that is, a 200 OK response will be sent by the API server before the owner object gets deleted.
docs/user-guide/jobs/work-queue-2/index.md
+1 -1
View File
@@ -31,7 +31,7 @@ Here is an overview of the steps in this example:
## Starting Redis
For this example, for simplicitly, we will start a single instance of Redis.
See the [Redis Example](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/redis/README.md) for an example
See the [Redis Example](https://github.com/kubernetes/kubernetes/tree/master/examples/guestbook) for an example
of deploying Redis scalably and redundantly.
Start a temporary Pod running Redis and a service so we can find it.
docs/user-guide/kubectl-cheatsheet.md
+1 -1
View File
@@ -200,7 +200,7 @@ $ kubectl logs my-pod # dump pod logs (stdout)
$ kubectl logs -f my-pod # stream pod logs (stdout)
$ kubectl run -i --tty busybox --image=busybox -- sh # Run pod as interactive shell
$ kubectl attach my-pod -i # Attach to Running Container
$ kubectl port-forward my-pod 5000 6000 # Forward port 6000 of Pod to your to 5000 on your local machine
$ kubectl port-forward my-pod 5000:6000 # Forward port 6000 of Pod to your to 5000 on your local machine
$ kubectl port-forward my-svc 6000 # Forward port to service
$ kubectl exec my-pod -- ls / # Run command in existing pod (1 container case)
$ kubectl exec my-pod -c my-container -- ls / # Run command in existing pod (multi-container case)
docs/user-guide/petset.md
+2 -2
View File
@@ -42,7 +42,7 @@ This doc assumes familiarity with the following Kubernetes concepts:
* [Cluster DNS](/docs/admin/dns/)
* [Headless Services](/docs/user-guide/services/#headless-services)
* [Persistent Volumes](/docs/user-guide/volumes/)
* [Persistent Volume Provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md)
* [Persistent Volume Provisioning](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/README.md)
You need a working Kubernetes cluster at version >= 1.3, with a healthy DNS [cluster addon](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md) at version >= 15. You cannot use PetSet on a hosted Kubernetes provider that has disabled `alpha` resources.
@@ -98,7 +98,7 @@ Before you start deploying applications as PetSets, there are a few limitations
* PetSet is an *alpha* resource, not available in any Kubernetes release prior to 1.3.
* As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver, and in fact most likely will be disabled on hosted offerings of Kubernetes.
* The only updatable field on a PetSet is `replicas`
* The storage for a given pet must either be provisioned by a [persistent volume provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that persistent volume provisioning is also currently in alpha.
* The storage for a given pet must either be provisioned by a [persistent volume provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that persistent volume provisioning is also currently in alpha.
* Deleting and/or scaling a PetSet down will *not* delete the volumes associated with the PetSet. This is done to ensure safety first, your data is more valuable than an auto purge of all related PetSet resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**.
* All PetSets currently require a "governing service", or a Service responsible for the network identity of the pets. The user is responsible for this Service.
* Updating an existing PetSet is currently a manual process, meaning you either need to deploy a new PetSet with the new image version, or orphan Pets one by one, update their image, and join them back to the cluster.
docs/user-guide/pods/init-container.md
+2 -2
View File
@@ -20,7 +20,7 @@ the next one is started. If the init container fails, Kubernetes will restart
the pod until the init container succeeds. If a pod is marked as `RestartNever`,
the pod will fail if the init container fails.
You specify a container as an init container by adding an annotation
You specify a container as an init container by adding an annotation.
The annotation key is `pod.beta.kubernetes.io/init-containers`. The annotation
value is a JSON array of [objects of type `v1.Container`
](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_container)
@@ -155,7 +155,7 @@ reasons:
* An init container image is changed by a user updating the Pod Spec.
* App container image changes only restart the app container.
* The pod infrastructure container is restarted
* The pod infrastructure container is restarted.
* This is uncommon and would have to be done by someone with root access to nodes.
* All containers in a pod are terminated, requiring a restart (RestartPolicyAlways) AND the record of init container completion has been lost due to garbage collection.
docs/user-guide/pods/pod-spec-common.json
+1 -1
View File
@@ -24,7 +24,7 @@
}
],
"resources": {
"cpu": ""
"cpu": "",
"memory": ""
}
}
docs/user-guide/secrets/index.md
+67 -7
View File
@@ -372,6 +372,41 @@ files.
When a secret being already consumed in a volume is updated, projected keys are eventually updated as well.
The update time depends on the kubelet syncing period.
#### Optional Secrets as Files from a Pod
Volumes and files provided by a Secret can be also be marked as optional.
The Secret or the key within a Secret does not have to exist. The mount path for
such items will always be created.
```json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "mypod",
"namespace": "myns"
},
"spec": {
"containers": [{
"name": "mypod",
"image": "redis",
"volumeMounts": [{
"name": "foo",
"mountPath": "/etc/foo"
}]
}],
"volumes": [{
"name": "foo",
"secret": {
"secretName": "mysecret",
"defaultMode": 256,
"optional": true
}
}]
}
}
```
#### Using Secrets as Environment Variables
To use a secret in an environment variable in a pod:
@@ -418,6 +453,30 @@ $ echo $SECRET_PASSWORD
1f2d1e2e67df
```
#### Optional Secrets from Environment Variables
You may not want to require all your secrets to exist. They can be marked as
optional as shown in the pod:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: optional-secret-env-pod
spec:
containers:
- name: mycontainer
image: redis
env:
- name: OPTIONAL_SECRET
valueFrom:
secretKeyRef:
name: mysecret
key: username
optional: true
restartPolicy: Never
```
#### Using imagePullSecrets
An imagePullSecret is a way to pass a secret that contains a Docker (or other) image registry
@@ -449,7 +508,8 @@ can be automatically attached to pods based on their service account.
Secret volume sources are validated to ensure that the specified object
reference actually points to an object of type `Secret`. Therefore, a secret
needs to be created before any pods that depend on it.
needs to be created before any pods that depend on it, unless it is marked as
optional.
Secret API objects reside in a namespace. They can only be referenced by pods
in that same namespace.
@@ -469,12 +529,12 @@ not common ways to create pods.)
When a pod is created via the API, there is no check whether a referenced
secret exists. Once a pod is scheduled, the kubelet will try to fetch the
secret value. If the secret cannot be fetched because it does not exist or
because of a temporary lack of connection to the API server, kubelet will
periodically retry. It will report an event about the pod explaining the
reason it is not started yet. Once the secret is fetched, the kubelet will
create and mount a volume containing it. None of the pod's containers will
start until all the pod's volumes are mounted.
secret value. If a required secret cannot be fetched because it does not
exist or because of a temporary lack of connection to the API server, the
kubelet will periodically retry. It will report an event about the pod
explaining the reason it is not started yet. Once the secret is fetched, the
kubelet will create and mount a volume containing it. None of the pod's
containers will start until all the pod's volumes are mounted.
## Use cases
docs/user-guide/sharing-clusters.md
+1 -2
View File
@@ -105,8 +105,7 @@ and/or run `kubectl config -h`.
1. `--kubeconfig=/path/to/.kube/config` command line flag
2. `KUBECONFIG=/path/to/.kube/config` env variable
3. `$PWD/.kube/config`
4. `$HOME/.kube/config`
3. `$HOME/.kube/config`
If you create clusters A, B on host1, and clusters C, D on host2, you can
make all four clusters available on both hosts by running
docs/user-guide/thirdpartyresources.md
+3
View File
@@ -9,6 +9,9 @@ title: Third Party Resources
## What is ThirdPartyResource?
**WARNING: ThirdPartyResources are not yet considered stable, and the API and/or storage could change before GA.
Development and outstanding issues are tracked at [https://github.com/kubernetes/features/issues/95](https://github.com/kubernetes/features/issues/95).**
Kubernetes comes with many built-in API objects. However, there are often times when you might need to extend Kubernetes with their own API objects in order to do custom automation.
`ThirdPartyResource` objects are a way to extend the Kubernetes API with a new API object type. The new API object type will be given an API endpoint URL and support CRUD operations, and watch API. You can then create custom objects using this API endpoint. You can think of `ThirdPartyResources` as being much like the schema for a database table. Once you have created the table, you can then start storing rows in the table. Once created, `ThirdPartyResources` can act as the data model behind custom controllers or automation programs.
docs/user-guide/ui.md
+3 -3
View File
@@ -42,9 +42,9 @@ The UI can _only_ be accessed from the machine where the command is executed. Se
You may access the UI directly via the Kubernetes master apiserver. Open a browser and navigate to `https://<kubernetes-master>/ui`, where `<kubernetes-master>` is IP address or domain name of the Kubernetes
master.
Please note, this works only if the apiserver is set up to allow authentication with username and password. This is not currently the case with the some setup tools (e.g., `kubeadm`). Refer to the [authentication admin documentation](/docs/admin/authentication/) for information on how to configure authentication manually.
Please note, this works only if the apiserver is set up to allow authentication with username and password. This is not currently the case with some setup tools (e.g., `kubeadm`). Refer to the [authentication admin documentation](/docs/admin/authentication/) for information on how to configure authentication manually.
If the username and password is configured but unknown to you, then use `kubectl config view` to find it.
If the username and password are configured but unknown to you, then use `kubectl config view` to find it.
## Welcome view
@@ -66,7 +66,7 @@ The deploy wizard expects that you provide the following information:
- **App name** (mandatory): Name for your application. A [label](/docs/user-guide/labels/) with the name will be added to the Deployment and Service, if any, that will be deployed.
The application name must be unique within the selected Kubernetes [namespace](/docs/admin/namespaces/). It must start and end with a lowercase character, and contain only lowercase letters, numbers and dashes (-). It is limited to 24 characters. Leading and trailing spaces are ignored.
The application name must be unique within the selected Kubernetes [namespace](/docs/admin/namespaces/). It must start with a lowercase character, and end with a lowercase character or a number, and contain only lowercase letters, numbers and dashes (-). It is limited to 24 characters. Leading and trailing spaces are ignored.
- **Container image** (mandatory): The URL of a public Docker [container image](/docs/user-guide/images/) on any registry, or a private image (commonly hosted on the Google Container Registry or Docker Hub). The container image specification must end with a colon.
docs/user-guide/update-demo/index.md
+7 -7
View File
@@ -1,9 +1,9 @@
---
assignees:
- mikedanese
title: Rolling Update Demo
---
---
assignees:
- mikedanese
title: Rolling Update Demo
---
This example demonstrates the usage of Kubernetes to perform a [rolling update](/docs/user-guide/kubectl/kubectl_rolling-update/) on a running group of [pods](/docs/user-guide/pods/). See [here](/docs/user-guide/managing-deployments/#updating-your-application-without-a-service-outage) to understand why you need a rolling update. Also check [rolling update design document](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/simple-rolling-update.md) for more information.
The files for this example are viewable in [our docs repo
@@ -67,7 +67,7 @@ The rolling-update command in kubectl will do 2 things:
Watch the [demo website](http://localhost:8001/static/index.html), it will update one pod every 10 seconds until all of the pods have the new image.
Note that the new replication controller definition does not include the replica count, so the current replica count of the old replication controller is preserved.
But if the replica count had been specified, the final replica count of the new replication controller will be equal this number.
But if the replica count had been specified, the final replica count of the new replication controller will be equal to this number.
### Step Five: Bring down the pods
images/docs/admin/k8s_oidc_login.svg
+1
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB