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/admin/authentication.md b/docs/admin/authentication.md index 4bbd0a4fee..a7cca01126 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 @@ -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 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 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 diff --git a/docs/admin/federation/index.md b/docs/admin/federation/index.md index 59a0199d7b..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 @@ -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: diff --git a/docs/admin/ha-master-gce.md b/docs/admin/ha-master-gce.md index 91e0019272..025035cca7 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 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 diff --git a/docs/admin/limitrange/index.md b/docs/admin/limitrange/index.md index 2241cbb140..3a31b9e732 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 @@ -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 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. 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 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 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 diff --git a/docs/admin/static-pods.md b/docs/admin/static-pods.md index 4766002917..8c9e482d0d 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 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/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/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index a6fc28bfb0..4f4a432185 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 --- @@ -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. 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` diff --git a/docs/getting-started-guides/ubuntu/index.md b/docs/getting-started-guides/ubuntu/index.md index 9fa4728bed..5e706f0add 100644 --- a/docs/getting-started-guides/ubuntu/index.md +++ b/docs/getting-started-guides/ubuntu/index.md @@ -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) 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) 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 %} 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) 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

    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/) 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: 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/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). diff --git a/docs/user-guide/configmap/index.md b/docs/user-guide/configmap/index.md index d630ed2aa8..3227e416c0 100644 --- a/docs/user-guide/configmap/index.md +++ b/docs/user-guide/configmap/index.md @@ -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. 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 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. 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. 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. 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) 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. 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. 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": "" } } 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 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 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. diff --git a/docs/user-guide/ui.md b/docs/user-guide/ui.md index de50ccde00..da2b2e611c 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 @@ -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. 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 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