From 5244bb8b6eac6faf9bb610139788d49dc57447f4 Mon Sep 17 00:00:00 2001 From: Marc Boorshtein Date: Mon, 16 Jan 2017 08:12:43 -0500 Subject: [PATCH 01/43] integrated docs from ts.com wiki w/o product info --- docs/admin/authentication.md | 145 ++++++++++++++++++++------- images/docs/admin/k8s_oidc_login.svg | 1 + 2 files changed, 112 insertions(+), 34 deletions(-) create mode 100644 images/docs/admin/k8s_oidc_login.svg diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index 4bbd0a4fee..1cfa8c5f13 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -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 @@ -222,44 +222,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 +446,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 +479,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 diff --git a/images/docs/admin/k8s_oidc_login.svg b/images/docs/admin/k8s_oidc_login.svg new file mode 100644 index 0000000000..f9b5bbd93d --- /dev/null +++ b/images/docs/admin/k8s_oidc_login.svg @@ -0,0 +1 @@ +IdentityProviderKubectlUser1.LogintoIdP2.Provideacces_token,id_tokenandrefresh_tokenAPIServer3.Callkubectlwith --tokenbeingtheid_tokenORaddtokensto .kubectl/config4.Authorization:Bearer...8.Authorized :performactionandreturnresult9.Returnresult6.HastheJWTexpired?(iat +exp)7.UserAuthorized?5.IsJWTsignaturevalid? \ No newline at end of file From fe1640a71e186235865f94b8dbcb0350f98cda64 Mon Sep 17 00:00:00 2001 From: Peter Lee Date: Wed, 18 Jan 2017 16:48:45 +0800 Subject: [PATCH 02/43] fix yaml source links of addons --- docs/admin/cluster-large.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/cluster-large.md b/docs/admin/cluster-large.md index 08d6d6c0d8..13788fdffb 100644 --- a/docs/admin/cluster-large.md +++ b/docs/admin/cluster-large.md @@ -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 From 56bac5a74938bb907630266799ff9318e0ed1a5c Mon Sep 17 00:00:00 2001 From: ahawtho Date: Wed, 18 Jan 2017 09:48:56 -0500 Subject: [PATCH 03/43] Fix link on environment-guide The 'pod definition' link in the 'Query the service' section had an incorrect link. --- docs/user-guide/environment-guide/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/environment-guide/index.md b/docs/user-guide/environment-guide/index.md index 417cf5be33..cbdd806ecd 100644 --- a/docs/user-guide/environment-guide/index.md +++ b/docs/user-guide/environment-guide/index.md @@ -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 From 8f37b020b0042a52493169f1ba0954c41446f611 Mon Sep 17 00:00:00 2001 From: Oskar Pearson Date: Thu, 19 Jan 2017 07:32:39 +0000 Subject: [PATCH 04/43] Replace Kubectl instructions with reference to authoritative page This page previously included instructions to use curl to download and install Kubectl via http, rather than with https. This exposed the end user to man-in-the-middle attacks. Additionally, the instructions given here are slightly different from the authoritative page at https://kubernetes.io/docs/getting-started-guides/kubectl/ - which covers useful things like getting the latest release and setting up tab autocompletion. Rather than just change 'http' to 'https' in the URLs here, I've updated the minikube setup page to include a reference to the kubectl setup page. --- docs/getting-started-guides/minikube.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index a6fc28bfb0..49a64269bd 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -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. From 354ba657039f2d6b423ee09bb3bd6c8293b55f4b Mon Sep 17 00:00:00 2001 From: euan-am Date: Thu, 19 Jan 2017 10:09:51 +0200 Subject: [PATCH 05/43] Port-forward to local port documentation fix The port-forward command was incorrect for the documentation description for forwarding a local port to a pod --- docs/user-guide/kubectl-cheatsheet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/kubectl-cheatsheet.md b/docs/user-guide/kubectl-cheatsheet.md index c16e7c264d..c147304a7d 100644 --- a/docs/user-guide/kubectl-cheatsheet.md +++ b/docs/user-guide/kubectl-cheatsheet.md @@ -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) From 1a0e15c915960e392d407c50aaadff43e704c68d Mon Sep 17 00:00:00 2001 From: Matt Rickard Date: Thu, 19 Jan 2017 10:17:23 -0800 Subject: [PATCH 06/43] Change reviewers of minikube to r2d4 and aprindle --- docs/getting-started-guides/minikube.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index a6fc28bfb0..9a4d06e210 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -1,8 +1,8 @@ --- assignees: - dlorenc -- janetkuo -- jlowdermilk +- r2d4 +- aaron-prindle title: Running Kubernetes Locally via Minikube --- From b8e105f7a8973fc90166701c0d2c79fb39f2b26f Mon Sep 17 00:00:00 2001 From: scjane Date: Fri, 20 Jan 2017 13:56:00 +0800 Subject: [PATCH 07/43] Update ui.md --- docs/user-guide/ui.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/ui.md b/docs/user-guide/ui.md index de50ccde00..818573e0da 100644 --- a/docs/user-guide/ui.md +++ b/docs/user-guide/ui.md @@ -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:///ui`, where `` 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 From 5738bcfb5029f7402975d4ff03b12c7dd8ab565c Mon Sep 17 00:00:00 2001 From: scjane Date: Fri, 20 Jan 2017 17:50:59 +0800 Subject: [PATCH 08/43] Update garbage-collection.md --- docs/user-guide/garbage-collection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/garbage-collection.md b/docs/user-guide/garbage-collection.md index fe55949f1f..af90b4dd1a 100644 --- a/docs/user-guide/garbage-collection.md +++ b/docs/user-guide/garbage-collection.md @@ -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. From fa702ad1fe33510d5eb1553f059c38ac173415e5 Mon Sep 17 00:00:00 2001 From: tolleiv Date: Sat, 21 Jan 2017 00:38:46 +0100 Subject: [PATCH 09/43] Update dead link with link to ubuntu.com --- docs/getting-started-guides/ubuntu/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/ubuntu/index.md b/docs/getting-started-guides/ubuntu/index.md index 9fa4728bed..7211cc0e92 100644 --- a/docs/getting-started-guides/ubuntu/index.md +++ b/docs/getting-started-guides/ubuntu/index.md @@ -9,7 +9,7 @@ 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. From 559f404de7748fccba90665f180488436c9d676c Mon Sep 17 00:00:00 2001 From: tolleiv Date: Sat, 21 Jan 2017 00:09:46 +0100 Subject: [PATCH 10/43] Update Federation API resource listing --- docs/user-guide/federation/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/federation/index.md b/docs/user-guide/federation/index.md index 719a3e8174..cf1c1f96ed 100644 --- a/docs/user-guide/federation/index.md +++ b/docs/user-guide/federation/index.md @@ -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/) - [API reference docs](/docs/federation/api-reference/) lists all the resources supported by federation apiserver. From b35d379dd1c177885271a3ea74c3d4c717f89b83 Mon Sep 17 00:00:00 2001 From: scjane Date: Sun, 22 Jan 2017 10:28:01 +0800 Subject: [PATCH 11/43] Update init-container.md --- docs/user-guide/pods/init-container.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/pods/init-container.md b/docs/user-guide/pods/init-container.md index b6f0cece35..ab743f2fd8 100644 --- a/docs/user-guide/pods/init-container.md +++ b/docs/user-guide/pods/init-container.md @@ -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. From 2efa5ab9d22ae7fc74d53060903ed22814c08149 Mon Sep 17 00:00:00 2001 From: bruceauyeung Date: Sun, 22 Jan 2017 11:05:04 +0800 Subject: [PATCH 12/43] fix unreachable links Signed-off-by: bruceauyeung --- docs/user-guide/compute-resources.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/compute-resources.md b/docs/user-guide/compute-resources.md index 2e524e9117..d2856f50aa 100644 --- a/docs/user-guide/compute-resources.md +++ b/docs/user-guide/compute-resources.md @@ -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). From bc448028c59e3120c5e5e065743680df46bb98b0 Mon Sep 17 00:00:00 2001 From: Omer Zach Date: Sat, 21 Jan 2017 21:21:15 -0800 Subject: [PATCH 13/43] Fix typo in index.md --- docs/tasks/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tasks/index.md b/docs/tasks/index.md index c16a22af7f..242c1dca75 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -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/) From 83ba9575f9ae4faba38b57c6d9f6d0889259cd55 Mon Sep 17 00:00:00 2001 From: Anthony Yeh Date: Wed, 18 Jan 2017 14:25:06 -0800 Subject: [PATCH 14/43] Use subPath to keep data dir out of volume root. The data dir should not be at the root of the volume, because many volume types create files or directories there automatically. The database initialization script requires the data dir to be empty, and we shouldn't try to guess which files may exist. In particular, by retaining lost+found, it also becomes possible to recover files that end up there. --- docs/tutorials/stateful-application/mysql-statefulset.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/stateful-application/mysql-statefulset.yaml b/docs/tutorials/stateful-application/mysql-statefulset.yaml index 106f77cd99..d8ee2d9ac9 100644 --- a/docs/tutorials/stateful-application/mysql-statefulset.yaml +++ b/docs/tutorials/stateful-application/mysql-statefulset.yaml @@ -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: From ac7d47d03df0324ab2dee988ce7c8a78e21a906d Mon Sep 17 00:00:00 2001 From: scjane Date: Tue, 24 Jan 2017 14:09:53 +0800 Subject: [PATCH 15/43] Update cluster-management.md --- docs/admin/cluster-management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/admin/cluster-management.md b/docs/admin/cluster-management.md index 5bcdb8b8f3..310128fd77 100644 --- a/docs/admin/cluster-management.md +++ b/docs/admin/cluster-management.md @@ -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/ 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/` 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 From 32088c5f5df5d6e7fff040f8d12a9496d445d65e Mon Sep 17 00:00:00 2001 From: scjane Date: Tue, 24 Jan 2017 16:44:00 +0800 Subject: [PATCH 16/43] Update index.md --- docs/admin/namespaces/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/admin/namespaces/index.md b/docs/admin/namespaces/index.md index b723a9c361..887f14cd91 100644 --- a/docs/admin/namespaces/index.md +++ b/docs/admin/namespaces/index.md @@ -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 From 511272b6ab8b02aa752fa987c22ade1970d3cf0c Mon Sep 17 00:00:00 2001 From: scjane Date: Tue, 24 Jan 2017 17:29:24 +0800 Subject: [PATCH 17/43] Update walkthrough.md --- docs/admin/namespaces/walkthrough.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/namespaces/walkthrough.md b/docs/admin/namespaces/walkthrough.md index b9c509697c..7576d2c2e0 100644 --- a/docs/admin/namespaces/walkthrough.md +++ b/docs/admin/namespaces/walkthrough.md @@ -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 From b58176b07d2e7c15754873c46c691995d3cf5d2a Mon Sep 17 00:00:00 2001 From: scjane Date: Tue, 24 Jan 2017 18:41:00 +0800 Subject: [PATCH 18/43] Update index.md --- docs/admin/limitrange/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/limitrange/index.md b/docs/admin/limitrange/index.md index 2241cbb140..b1ade5c52f 100644 --- a/docs/admin/limitrange/index.md +++ b/docs/admin/limitrange/index.md @@ -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 From c407429fe917f7102ed6451c8a25600a9d45d9bd Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Tue, 24 Jan 2017 00:25:06 -0500 Subject: [PATCH 19/43] Add link to feature issue for TPR --- docs/user-guide/thirdpartyresources.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/thirdpartyresources.md b/docs/user-guide/thirdpartyresources.md index b6e608b3b9..21728f3021 100644 --- a/docs/user-guide/thirdpartyresources.md +++ b/docs/user-guide/thirdpartyresources.md @@ -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. From 6cfdb404bcf336c49fb014bcd22e05a869546e28 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Tue, 24 Jan 2017 10:11:26 -0800 Subject: [PATCH 20/43] fixed capitalization typo changed 'cpu' to 'CPU' when not in config text --- docs/admin/limitrange/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/limitrange/index.md b/docs/admin/limitrange/index.md index b1ade5c52f..3a31b9e732 100644 --- a/docs/admin/limitrange/index.md +++ b/docs/admin/limitrange/index.md @@ -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 From c24ed09231b7780f23fc2a7e80c6faade749f68d Mon Sep 17 00:00:00 2001 From: Huamin Chen Date: Tue, 17 Jan 2017 15:24:31 +0000 Subject: [PATCH 21/43] fix persistent volume example link Signed-off-by: Huamin Chen --- docs/concepts/abstractions/controllers/statefulsets.md | 2 +- docs/tutorials/stateful-application/zookeeper.md | 2 +- docs/user-guide/petset.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/concepts/abstractions/controllers/statefulsets.md b/docs/concepts/abstractions/controllers/statefulsets.md index fb48e63ae0..fd7ac3277b 100644 --- a/docs/concepts/abstractions/controllers/statefulsets.md +++ b/docs/concepts/abstractions/controllers/statefulsets.md @@ -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. diff --git a/docs/tutorials/stateful-application/zookeeper.md b/docs/tutorials/stateful-application/zookeeper.md index 836192de9f..ba2bb219d6 100644 --- a/docs/tutorials/stateful-application/zookeeper.md +++ b/docs/tutorials/stateful-application/zookeeper.md @@ -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) diff --git a/docs/user-guide/petset.md b/docs/user-guide/petset.md index 3247cf5a42..afdca343a0 100644 --- a/docs/user-guide/petset.md +++ b/docs/user-guide/petset.md @@ -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. From 56d88e956615acc9f6545ab56497ce8244afb96f Mon Sep 17 00:00:00 2001 From: Yonathan Randolph Date: Thu, 12 Jan 2017 14:08:10 -0800 Subject: [PATCH 22/43] Fix code formatting --- docs/admin/static-pods.md | 56 +++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/admin/static-pods.md b/docs/admin/static-pods.md index 4766002917..74aee8f926 100644 --- a/docs/admin/static-pods.md +++ b/docs/admin/static-pods.md @@ -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 </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 </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 From b9f53d7991169226ac0bf6353aadf9ca6a9f66c1 Mon Sep 17 00:00:00 2001 From: Yonathan Randolph Date: Thu, 12 Jan 2017 15:01:14 -0800 Subject: [PATCH 23/43] Fix typo tcp -> TCP --- docs/admin/static-pods.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/static-pods.md b/docs/admin/static-pods.md index 74aee8f926..8c9e482d0d 100644 --- a/docs/admin/static-pods.md +++ b/docs/admin/static-pods.md @@ -44,7 +44,7 @@ spec: ports: - name: web containerPort: 80 - protocol: tcp + protocol: TCP EOF ``` From 64f86459e0a80d40ebec31609b246961cd3111f8 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Wed, 11 Jan 2017 10:16:44 -0500 Subject: [PATCH 24/43] Fix broken link. --- docs/getting-started-guides/ubuntu/networking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started-guides/ubuntu/networking.md b/docs/getting-started-guides/ubuntu/networking.md index 7b4d3bcb28..54ca15c6ad 100644 --- a/docs/getting-started-guides/ubuntu/networking.md +++ b/docs/getting-started-guides/ubuntu/networking.md @@ -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 %} \ No newline at end of file +{% include templates/task.md %} From 5ac4ac6eba08090abb191e8093582a79302d7215 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Fri, 13 Jan 2017 10:40:12 -0500 Subject: [PATCH 25/43] Add conjure-up instructions. --- docs/getting-started-guides/ubuntu/index.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/getting-started-guides/ubuntu/index.md b/docs/getting-started-guides/ubuntu/index.md index 7211cc0e92..5e706f0add 100644 --- a/docs/getting-started-guides/ubuntu/index.md +++ b/docs/getting-started-guides/ubuntu/index.md @@ -13,7 +13,23 @@ There are multiple ways to run a Kubernetes cluster with Ubuntu. These pages exp 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) From 3d39da4670a9b00bb206e8cafcbaa1717cdcc772 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Wed, 18 Jan 2017 15:12:37 -0500 Subject: [PATCH 26/43] Add github.com as a network dependency. --- docs/getting-started-guides/ubuntu/installation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/getting-started-guides/ubuntu/installation.md b/docs/getting-started-guides/ubuntu/installation.md index b8f892dc46..cc93995144 100644 --- a/docs/getting-started-guides/ubuntu/installation.md +++ b/docs/getting-started-guides/ubuntu/installation.md @@ -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) From e2a732f4ebfdac2ff4406d48dd47ec70ab4c2a0c Mon Sep 17 00:00:00 2001 From: xilabao Date: Wed, 11 Jan 2017 23:14:36 -0600 Subject: [PATCH 27/43] Update groups to passwordfile ref to https://github.com/kubernetes/kubernetes/pull/39651 --- docs/admin/authentication.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index 1cfa8c5f13..a7cca01126 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -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 From d09498f7c1c9453b4c46c63b3c8c7d77f79d55d5 Mon Sep 17 00:00:00 2001 From: Bogdan Dobrelya Date: Tue, 10 Jan 2017 14:54:54 +0100 Subject: [PATCH 28/43] Add docs for Kargo installer for Kubernetes Add documentation for Getting Started guides. Kargo is an incubated Kubernetes project https://github.com/kubernetes-incubator/kargo. Signed-off-by: Bogdan Dobrelya --- _data/guides.yml | 1 + _data/tasks.yml | 2 +- docs/getting-started-guides/kargo.md | 104 +++++++++++++++++++++++++++ docs/index.md | 1 + 4 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started-guides/kargo.md diff --git a/_data/guides.yml b/_data/guides.yml index fdade5b1ec..f66d0706ee 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -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 diff --git a/_data/tasks.yml b/_data/tasks.yml index 13315bf5ed..231a583524 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -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 diff --git a/docs/getting-started-guides/kargo.md b/docs/getting-started-guides/kargo.md new file mode 100644 index 0000000000..93f1373c75 --- /dev/null +++ b/docs/getting-started-guides/kargo.md @@ -0,0 +1,104 @@ +--- +title: Installing Kubernetes On-premise/Cloud Providers with Kargo +--- + + + +## 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) + diff --git a/docs/index.md b/docs/index.md index 24814e55ae..1201403936 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,6 +20,7 @@ title: Kubernetes Documentation
  • Minikube: Install a single-node Kubernetes cluster on your local machine for development and testing.
  • Installing Kubernetes on AWS with kops: Bring up a complete Kubernetes cluster on Amazon Web Services, using a tool called kops.
  • Installing Kubernetes on Linux with kubeadm (Alpha): Install a secure Kubernetes cluster on any pre-existing machines running Linux, using the built-in kubeadm tool.
    • +
  • Installing Kubernetes On-premise/Cloud Providers with Kargo: Deploy a Kubernetes cluster on-premise baremetal or hosted on cloud providers, with Ansible and kargo tools.

    • Guides, Tutorials, Tasks, and Concepts

    From b1dfb93e1b39b4719330cdf3162a9a6d4d0a3887 Mon Sep 17 00:00:00 2001 From: luks Date: Mon, 9 Jan 2017 23:18:17 -0200 Subject: [PATCH 29/43] minor fix and explain cluster-cidr/allocate-node-cidr in the controller-manager section --- docs/getting-started-guides/scratch.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/getting-started-guides/scratch.md b/docs/getting-started-guides/scratch.md index 9b53e28e78..f95f132be6 100644 --- a/docs/getting-started-guides/scratch.md +++ b/docs/getting-started-guides/scratch.md @@ -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` From 5e77cd1825c652c63fa5b3891cd1a7860ad49c03 Mon Sep 17 00:00:00 2001 From: Justin Nauman Date: Wed, 28 Dec 2016 14:54:52 -0600 Subject: [PATCH 30/43] Updates on the PV zone affinity documentation Updates docs around the PV distribution process per the linked issues --- docs/admin/multiple-zones.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/admin/multiple-zones.md b/docs/admin/multiple-zones.md index e215b31716..b6421e71c2 100644 --- a/docs/admin/multiple-zones.md +++ b/docs/admin/multiple-zones.md @@ -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 - < kubectl get pv --show-labels From d7ce58eacca7fccdebfd5c9f7d29dfa32d54c8f0 Mon Sep 17 00:00:00 2001 From: sallydeng Date: Mon, 23 Jan 2017 16:47:37 +0800 Subject: [PATCH 31/43] Update ui.md I installed gcr.io/google_containers/kubernetes-dashboard-amd64:v1.5.0. When I deploy a containerized app through dashboad ui, the appname can be "dxltest1" . The "dxltest1" can be deployed successfully. so the appname can be end with a number. --- docs/user-guide/ui.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/ui.md b/docs/user-guide/ui.md index 818573e0da..da2b2e611c 100644 --- a/docs/user-guide/ui.md +++ b/docs/user-guide/ui.md @@ -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. From 4bbd9ba6ce31884d692abd54316b178f205f1abe Mon Sep 17 00:00:00 2001 From: scjane Date: Fri, 20 Jan 2017 16:22:22 +0800 Subject: [PATCH 32/43] Update index.md --- docs/user-guide/update-demo/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/update-demo/index.md b/docs/user-guide/update-demo/index.md index 7f0952348c..f2e3f8a0f2 100644 --- a/docs/user-guide/update-demo/index.md +++ b/docs/user-guide/update-demo/index.md @@ -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 From 0fd32489a85bcfd77639c54bddf18609dbbafe39 Mon Sep 17 00:00:00 2001 From: scjane Date: Tue, 24 Jan 2017 16:24:57 +0800 Subject: [PATCH 33/43] Update ha-master-gce.md --- docs/admin/ha-master-gce.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/ha-master-gce.md b/docs/admin/ha-master-gce.md index 91e0019272..3eb2918655 100644 --- a/docs/admin/ha-master-gce.md +++ b/docs/admin/ha-master-gce.md @@ -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: +
    1. Add a new replica in place of the old one:
    ```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 speed 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 From f99d34ff1ab2afb9c6cb1f129ce07c7d7d11c329 Mon Sep 17 00:00:00 2001 From: Cemalettin Koc Date: Wed, 18 Jan 2017 19:32:34 +0200 Subject: [PATCH 34/43] Align kubeconfig resolution with the rest of documentation It seems that this part has a missing documentation. Here is the reference of `kubectl` configuration. https://kubernetes.io/docs/user-guide/kubectl/kubectl_config/ --- docs/user-guide/sharing-clusters.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/user-guide/sharing-clusters.md b/docs/user-guide/sharing-clusters.md index c21acca84a..4faf7d9826 100644 --- a/docs/user-guide/sharing-clusters.md +++ b/docs/user-guide/sharing-clusters.md @@ -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 From d890d8f97a653562ea0094e9c4a4da3085d36668 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Tue, 24 Jan 2017 15:40:00 -0800 Subject: [PATCH 35/43] Fixed typo changed "speed" to "sped" for proper tense --- docs/admin/ha-master-gce.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/ha-master-gce.md b/docs/admin/ha-master-gce.md index 3eb2918655..025035cca7 100644 --- a/docs/admin/ha-master-gce.md +++ b/docs/admin/ha-master-gce.md @@ -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) +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 From 7abcc6c8540a7b0a4f6712e77e0f5cb134271bed Mon Sep 17 00:00:00 2001 From: Michael Fraenkel Date: Tue, 24 Jan 2017 06:31:10 -0700 Subject: [PATCH 36/43] Document new optional support for ConfigMap and Secret Corresponds to proposal https://github.com/kubernetes/community/pull/175 --- docs/user-guide/configmap/index.md | 70 ++++++++++++++++++++++++++-- docs/user-guide/secrets/index.md | 74 +++++++++++++++++++++++++++--- 2 files changed, 134 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/configmap/index.md b/docs/user-guide/configmap/index.md index d630ed2aa8..2e80ec8d9b 100644 --- a/docs/user-guide/configmap/index.md +++ b/docs/user-guide/configmap/index.md @@ -291,6 +291,37 @@ 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, its output will include the lines: + +```shell +``` + ### 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 +453,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 +580,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. diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index 6942b52ff3..7da0f446fd 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -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 From 324451c3378b4ba01d27e3db6117f86d0517a598 Mon Sep 17 00:00:00 2001 From: Michael Fraenkel Date: Tue, 24 Jan 2017 16:54:22 -0700 Subject: [PATCH 37/43] mend --- docs/user-guide/configmap/index.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/user-guide/configmap/index.md b/docs/user-guide/configmap/index.md index 2e80ec8d9b..3227e416c0 100644 --- a/docs/user-guide/configmap/index.md +++ b/docs/user-guide/configmap/index.md @@ -317,10 +317,7 @@ spec: restartPolicy: Never ``` -When this pod is run, its output will include the lines: - -```shell -``` +When this pod is run, the output will be empty. ### Use-Case: Set command-line arguments with ConfigMap From 220352d117c4bf774d7e2f2d766979fd077ba361 Mon Sep 17 00:00:00 2001 From: Scott Collier Date: Thu, 12 Jan 2017 17:11:24 -0600 Subject: [PATCH 38/43] removing word that doesn't flow correctly --- docs/admin/federation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/federation/index.md b/docs/admin/federation/index.md index 59a0199d7b..b9cd397514 100644 --- a/docs/admin/federation/index.md +++ b/docs/admin/federation/index.md @@ -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: From f331ebe332f0be66dd6d3f63ab78c504c6e15b44 Mon Sep 17 00:00:00 2001 From: divyenpatel Date: Mon, 16 Jan 2017 12:14:57 -0800 Subject: [PATCH 39/43] Updated known issues in docs/getting-started-guides/vsphere.md --- docs/getting-started-guides/vsphere.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/vsphere.md b/docs/getting-started-guides/vsphere.md index 36372144c6..ba07d14890 100644 --- a/docs/getting-started-guides/vsphere.md +++ b/docs/getting-started-guides/vsphere.md @@ -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) From 6afde69458e2c6878250fdcb9d564dfb053188df Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Wed, 11 Jan 2017 16:35:00 -0800 Subject: [PATCH 40/43] fixed broken link re: issue #1687 Updated link to go to https://github.com/kubernetes/kubernetes/tree/master/examples/guestbook which is a redis example mentioned in https://kubernetes.io/docs/samples/ --- docs/user-guide/jobs/work-queue-2/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/jobs/work-queue-2/index.md b/docs/user-guide/jobs/work-queue-2/index.md index 98d327d9a9..621be7f795 100644 --- a/docs/user-guide/jobs/work-queue-2/index.md +++ b/docs/user-guide/jobs/work-queue-2/index.md @@ -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. From e93bb9dc275120dfbe0b565f742ca55eec020a7f Mon Sep 17 00:00:00 2001 From: Hugues Malphettes Date: Wed, 25 Jan 2017 07:05:09 +0800 Subject: [PATCH 41/43] Format JSON: missing comma --- docs/user-guide/pods/pod-spec-common.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/pods/pod-spec-common.json b/docs/user-guide/pods/pod-spec-common.json index c449c34de5..8621593d07 100644 --- a/docs/user-guide/pods/pod-spec-common.json +++ b/docs/user-guide/pods/pod-spec-common.json @@ -24,7 +24,7 @@ } ], "resources": { - "cpu": "" + "cpu": "", "memory": "" } } From 0e1670ccb827891e451c224a1f670fa0adb0cb8a Mon Sep 17 00:00:00 2001 From: Scott Collier Date: Thu, 12 Jan 2017 17:04:08 -0600 Subject: [PATCH 42/43] looks like a couple of words got swapped when describing the ConfigMap for kube-dns, just fixing that up --- docs/admin/federation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/federation/index.md b/docs/admin/federation/index.md index b9cd397514..bb15fe09ff 100644 --- a/docs/admin/federation/index.md +++ b/docs/admin/federation/index.md @@ -236,7 +236,7 @@ metadata: name: kube-dns namespace: kube-system data: - federations: = + federations: = ``` where `` should be replaced by the name you want to give to your From 27d0048498cbef12631e35d2608b0a25349a54e6 Mon Sep 17 00:00:00 2001 From: scjane Date: Wed, 25 Jan 2017 17:25:31 +0800 Subject: [PATCH 43/43] Update master-node-communication.md --- docs/admin/master-node-communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/master-node-communication.md b/docs/admin/master-node-communication.md index 91ecff7ef9..d654fd5173 100644 --- a/docs/admin/master-node-communication.md +++ b/docs/admin/master-node-communication.md @@ -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.