diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..9dd8149a15 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing to Kubernetes Documentation + +**First off, thanks for taking the time to contribute!** + +The following is a set of guidelines for contributing to Kubernetes documentation, hosted at [Kubernetes.io](http://kubernetes.io/). +These are just guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. + +## Before you get started + +### Code of Conduct + +Kubernetes follows the [Cloud Native Computing Foundation (CNCF) Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to Sarah Novotny [sarahnovotny@google.com](mailto:sarahnovotny@google.com) and/or Dan Kohn [dan@linuxfoundation.org](mailto:dan@linuxfoundation.org). + +### Documentation and Site Decisions + +The [Kubernetes SIG Docs Discussion Group](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) is the discussion group for doc releases, suggested site improvements, and improving the doc contribution experience. If you are planning to be a regular contributor, join this group to stay informed and involved. + +### Style Guides and Templates + +Before submitting a pull request to create new content, please review the [Kubernetes.io style guide](http://kubernetes.io/docs/contribute/style-guide/) and follow the [instructions for using page templates](http://kubernetes.io/docs/contribute/page-templates/). + + +## Contributing to Documentation + +### Reporting Documentation Issues + +Kubernetes.io uses github issues to track documentation issues and requests. If you see a documentation issue, submit an issue using the following steps: + +1. Check the [kubernetes.io issues list](https://github.com/kubernetes/kubernetes.github.io/issues) as you might find out the issue is a duplicate. +2. Use the [included template for every new issue](https://github.com/kubernetes/kubernetes.github.io/issues/new). When you create a bug report, include as many details as possible and include suggested fixes to the issue. + +Note that code issues should be filed against the main kubernetes repository, while documentation issues should go in the kubernetes.io repository. + +### Submitting Documentation Pull Requests + +If you’re fixing an issue in the existing documentation, you should submit a PR against the master branch. Follow [these instructions to create a documentation pull request against the kubernetes.io repository](http://kubernetes.io/docs/contribute/create-pull-request/). diff --git a/LICENSE b/LICENSE index 5ee2946660..06c608dcf4 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,395 @@ -Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ +Attribution 4.0 International - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION +======================================================================= - 1. Definitions. +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. +Using Creative Commons Public Licenses - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. +======================================================================= - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. +Creative Commons Attribution 4.0 International Public License - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." +Section 1 -- Definitions. - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. +Section 2 -- Scope. - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. + a. License grant. - END OF TERMS AND CONDITIONS + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: - APPENDIX: How to apply the Apache License to your work. + a. reproduce and Share the Licensed Material, in whole or + in part; and - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. + b. produce, reproduce, and Share Adapted Material. - Copyright 2016 The Kubernetes Authors + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at + 3. Term. The term of this Public License is specified in Section + 6(a). - http://www.apache.org/licenses/LICENSE-2.0 + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index 381cd46567..2801eaead0 100644 --- a/README.md +++ b/README.md @@ -174,14 +174,7 @@ example. If creating an image for a doc, follow the section on "Docker images" from the Kubernetes repository. ## Partners -Kubernetes partners refers to the companies who contribute to the Kubernetes core codebase and/or extend their platform to support Kubernetes. Partners can get their logos added to the partner section of the [community page](http://k8s.io/community) by following the below steps and meeting the below logo specifications. Partners will also need to have a URL that is specific to integrating with Kubernetes ready; this URL will be the destination when the logo is clicked. - -* The partner product logo should be a transparent png image centered in a 215x125 px frame. (look at the existing logos for reference) -* The logo must link to a URL that is specific to integrating with Kubernetes, hosted on the partner's site. -* The logo should be named *product-name*_logo.png and placed in the `/images/community_logos` folder. -* The image reference (including the link to the partner URL) should be added in `community.html` under `
...
`. -* Please do not change the order of the existing partner images. Append your logo to the end of the list. -* Once completed and tested the look and feel, submit the pull request. +Kubernetes partners refers to the companies who contribute to the Kubernetes core codebase, extend their platform to support Kubernetes or provide managed services to users centered around the Kubernetes platform. Partners can get their services and offerings added to the [partner page](https://k8s.io/partners) by completing and submitting the [partner request form](https://goo.gl/qcSnZF). Once the information and assets are verified, the partner product/services will be listed in the partner page. This would typically take 7-10 days. ## Thank you! diff --git a/_data/guides.yml b/_data/guides.yml index 85c5dd4103..0c1a785720 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -14,6 +14,8 @@ toc: path: /docs/getting-started-guides/kops/ - title: Hello World on Google Container Engine path: /docs/hellonode/ + - title: Installing kubectl + path: /docs/getting-started-guides/kubectl/ - title: Downloading or Building Kubernetes path: /docs/getting-started-guides/binary_release/ - title: Online Training Course @@ -68,9 +70,9 @@ toc: section: - title: Example Walkthrough path: /docs/getting-started-guides/network-policy/walkthrough/ - - title: Using Calico for NetworkPolicy + - title: Using Calico for NetworkPolicy path: /docs/getting-started-guides/network-policy/calico/ - - title: Using Romana for NetworkPolicy + - title: Using Romana for NetworkPolicy path: /docs/getting-started-guides/network-policy/romana/ - title: Batch Jobs @@ -83,6 +85,8 @@ toc: path: /docs/user-guide/jobs/work-queue-1/ - title: Fine Parallel Processing using a Work Queue path: /docs/user-guide/jobs/work-queue-2/ + - title: Cron Jobs + path: /docs/user-guide/cron-jobs/ - title: Service Discovery and Load Balancing section: @@ -207,8 +211,6 @@ toc: path: /docs/getting-started-guides/ovirt/ - title: OpenStack Heat path: /docs/getting-started-guides/openstack-heat/ - - title: CoreOS on Multinode Cluster - path: /docs/getting-started-guides/coreos/coreos_multinode_cluster/ - title: rkt section: - title: Running Kubernetes with rkt @@ -233,12 +235,8 @@ toc: path: /docs/getting-started-guides/centos/centos_manual_config/ - title: CoreOS path: /docs/getting-started-guides/coreos - - title: CoreOS with Calico - path: /docs/getting-started-guides/coreos/bare_metal_calico/ - title: Ubuntu path: /docs/getting-started-guides/ubuntu/ - - title: Ubuntu Nodes with Calico - path: /docs/getting-started-guides/ubuntu-calico/ - title: Validate Node Setup path: /docs/admin/node-conformance - title: Portable Multi-Node Cluster @@ -297,7 +295,7 @@ toc: - title: Configuring kubelet Garbage Collection path: /docs/admin/garbage-collection/ - title: Configuring Out Of Resource Handling - path: /docs/admin/out-of-resource/ + path: /docs/admin/out-of-resource/ - title: Configuring Kubernetes with Salt path: /docs/admin/salt/ - title: Monitoring Node Health diff --git a/_data/reference.yml b/_data/reference.yml index 5d4fe17f7b..6f71d1677c 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -40,13 +40,13 @@ toc: path: /docs/api-reference/batch/v1/operations/ - title: Batch API Definitions path: /docs/api-reference/batch/v1/definitions/ - + - title: Extensions API section: - title: Extensions API Operations path: /docs/api-reference/extensions/v1beta1/operations/ - title: Extensions API Definitions - path: /docs/api-reference/extensions/v1beta1/definitions/ + path: /docs/api-reference/extensions/v1beta1/definitions/ - title: kubectl CLI section: @@ -172,7 +172,7 @@ toc: - title: kube-apiserver path: /docs/admin/kube-apiserver/ - title: kube-controller-manager - path: /docs/admin/kube-controller-manager/ + path: /docs/admin/kube-controller-manager/ - title: kube-proxy path: /docs/admin/kube-proxy/ - title: kube-scheduler @@ -183,33 +183,33 @@ toc: - title: Glossary section: - title: Annotations - path: /docs/user-guide/annotations/ + path: /docs/user-guide/annotations/ - title: Daemon Sets path: /docs/admin/daemons/ - - title: Deployments + - title: Deployments path: /docs/user-guide/deployments/ - title: Horizontal Pod Autoscaling - path: /docs/user-guide/horizontal-pod-autoscaling/ + path: /docs/user-guide/horizontal-pod-autoscaling/ - title: Images path: /docs/user-guide/images/ - title: Ingress Resources - path: /docs/user-guide/ingress/ + path: /docs/user-guide/ingress/ - title: Jobs - path: /docs/user-guide/jobs/ + path: /docs/user-guide/jobs/ - title: Labels and Selectors path: /docs/user-guide/labels/ - title: Names path: /docs/user-guide/identifiers/ - title: Namespaces path: /docs/user-guide/namespaces/ - - title: Network Policies - path: /docs/user-guide/networkpolicies/ + - title: Network Policies + path: /docs/user-guide/networkpolicies/ - title: Nodes - path: /docs/admin/node/ + path: /docs/admin/node/ - title: Persistent Volumes - path: /docs/user-guide/persistent-volumes/ + path: /docs/user-guide/persistent-volumes/ - title: Pet Sets - path: /docs/user-guide/petset/ + path: /docs/user-guide/petset/ - title: Pods path: /docs/user-guide/pods/ - title: Pod Security Policies @@ -217,11 +217,11 @@ toc: - title: Replica Sets path: /docs/user-guide/replicasets/ - title: Replication Controller - path: /docs/user-guide/replication-controller/ + path: /docs/user-guide/replication-controller/ - title: Resource Quotas - path: /docs/admin/resource-quota/ - - title: Scheduled Jobs - path: /docs/user-guide/scheduled-jobs/ + path: /docs/admin/resourcequota/ + - title: Cron Jobs + path: /docs/user-guide/cron-jobs/ - title: Secrets path: /docs/user-guide/secrets/ - title: Security Context @@ -244,11 +244,11 @@ toc: - title: Kubernetes Identity and Access Management path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/access.md - title: Kubernetes OpenVSwitch GRE/VxLAN networking - path: /docs/admin/ovs-networking/ + path: /docs/admin/ovs-networking/ - title: Security Contexts path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security_context.md - title: Security in Kubernetes - path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md + path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md - title: Federation section: @@ -269,6 +269,6 @@ toc: - title: Federation Components section: - title: federation-apiserver - path: /docs/admin/federation-apiserver.md + path: /docs/admin/federation-apiserver - title : federation-controller-mananger - path: /docs/admin/federation-controller-manager.md + path: /docs/admin/federation-controller-manager diff --git a/_data/support.yml b/_data/support.yml index e280c827d7..3e9ec08ee4 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -14,6 +14,8 @@ toc: path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ + - title: Documentation Style Guide + path: /docs/contribute/style-guide/ - title: Troubleshooting section: @@ -51,5 +53,3 @@ toc: path: https://github.com/kubernetes/kubernetes/milestones/ - title: Contributing to Kubernetes Documentation path: /editdocs/ - - title: New Template Instructions - path: /docs/templatedemos/ diff --git a/_data/tasks.yml b/_data/tasks.yml index 4c6cd1b709..9898fae32f 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -15,6 +15,14 @@ toc: section: - title: Using Port Forwarding to Access Applications in a Cluster path: /docs/tasks/access-application-cluster/port-forward-access-application-cluster/ + + +- title: Debugging Applications in a Cluster + section: + - title: Determining the Reason for Pod Failure + path: /docs/tasks/debug-application-cluster/determine-reason-pod-failure/ + + - title: Accessing the Kubernetes API section: - title: Using an HTTP Proxy to Access the Kubernetes API diff --git a/_data/tutorials.yml b/_data/tutorials.yml index f088ff4dc4..437e984314 100644 --- a/_data/tutorials.yml +++ b/_data/tutorials.yml @@ -54,4 +54,6 @@ toc: - title: Stateful Applications section: - title: StatefulSet Basics - path: /docs/tutorials/stateful-application/basic-stateful-set/ \ No newline at end of file + path: /docs/tutorials/stateful-application/basic-stateful-set/ + - title: Running a Single-Instance Stateful Application + path: /docs/tutorials/stateful-application/run-stateful-application/ diff --git a/_includes/footer.html b/_includes/footer.html index 15dacb72e0..5e724f710c 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -20,8 +20,10 @@ Events Calendar
+ Download K8s + Contribute to the K8s codebase
-
© {{ 'now' | date: "%Y" }} Kubernetes
+
© {{ 'now' | date: "%Y" }} The Kubernetes Authors | Distributed under CC BY 4.0
diff --git a/_includes/partner-script.js b/_includes/partner-script.js index f7447c63b7..a085ad1627 100644 --- a/_includes/partner-script.js +++ b/_includes/partner-script.js @@ -14,6 +14,13 @@ link: 'https://deis.com', blurb: 'Deis the creators of Helm, Workflow, and Steward, helps developers and operators build, deploy, manage and scale their applications on top of Kubernetes.' }, + { + type: 0, + name: 'StackPointCloud', + logo: 'stackpoint', + link: 'https://stackpoint.io', + blurb: 'StackPointCloud builds Stackpoint.io, the universal control plane for Kubernetes Anywhere -- compose and build your own infrastructure as easily as a DigitalOcean droplet at any public cloud provider.' + }, { type: 0, name: 'Sysdig Cloud', @@ -175,6 +182,20 @@ link: 'https://aporeto.com/trireme', blurb: 'Aporeto makes cloud-native applications secure by default without impacting developer velocity and works at any scale, on any cloud.' }, + { + type: 0, + name: 'Giant Swarm', + logo: 'giant_swarm', + link: 'https://giantswarm.io', + blurb: 'Giant Swarm provides fully-managed Kubernetes Clusters in your location of choice, so you can focus on your product.' + }, + { + type: 0, + name: 'Mirantis', + logo: 'mirantis', + link: 'https://content.mirantis.com/Containerizing-OpenStack-on-Kubernetes-Video-Landing-Page.html', + blurb: 'Mirantis builds and manages private clouds with open source software such as OpenStack, deployed as containers orchestrated by Kubernetes.' + }, { type: 1, name: 'Apprenda', @@ -203,6 +224,13 @@ link: 'https://deis.com/services/', blurb: 'Deis provides professional services and 24x7 operational support for any Kubernetes cluster managed by our global cluster operations team.' }, + { + type: 1, + name: 'StackPointCloud', + logo: 'stackpoint', + link: 'https://stackpoint.io', + blurb: 'StackPointCloud offers a wide range of support plans for managed Kubernetes clusters built through its universal control plane for Kubernetes Anywhere.' + }, { type: 1, name: 'Samsung SDS', @@ -237,7 +265,14 @@ logo: 'skippbox', link: 'http://www.skippbox.com/services/', blurb: 'Skippbox brings its Kubernetes expertise to help companies embrace Kubernetes on their way to digital transformation. Skippbox offers both professional services and expert training.' - } + }, + { + type: 1, + name: 'Endocode', + logo: 'endocode', + link: 'https://endocode.com/kubernetes/', + blurb: 'Endocode practices and teaches the open source way. Kernel to cluster - Dev to Ops. We offer Kubernetes trainings, services and support.' + } ] var isvContainer = document.getElementById('isvContainer') diff --git a/_layouts/docwithnav.html b/_layouts/docwithnav.html index 877ccc4e63..b97f92d53a 100755 --- a/_layouts/docwithnav.html +++ b/_layouts/docwithnav.html @@ -41,7 +41,7 @@ {% if notitle != "true" %}

{{ title }}

{% endif %} {{ content }}

Analytics - {% if page.url != "/404.html" and page.url != "/docs/search/" %}

+ {% if page.url != "/404.html" and page.url != "/docs/search/" %} Create Issue - Edit This Page + window.location.pathname)" class="button issue">Create an Issue + Edit this Page {% endif %} @@ -80,6 +80,34 @@ })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-36037335-10', 'auto'); ga('send', 'pageview'); + + // hide docs nav area if no nav is present, or if nav only contains a link to the current page + (function () { + window.addEventListener('DOMContentLoaded', init) + + // play nice with our neighbors + function init() { + window.removeEventListener('DOMContentLoaded', init) + hideNav() + } + + function hideNav(toc){ + if (!toc) toc = document.querySelector('#docsToc') + var container = toc.querySelector('.container') + + // container is built dynamically, so it may not be present on the first runloop + if (container) { + if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) { + toc.style.display = 'none' + document.getElementById('docsContent').style.width = '100%' + } + } else { + requestAnimationFrame(function () { + hideNav(toc) + }) + } + } + })(); diff --git a/_sass/_base.sass b/_sass/_base.sass index a8ac4b47c4..109124052f 100644 --- a/_sass/_base.sass +++ b/_sass/_base.sass @@ -389,6 +389,14 @@ footer display: block height: 0 overflow: hidden + + &.button + background-image: none + width: auto + height: auto + + &:hover + color: $blue a.twitter background-position: 0 0 @@ -874,11 +882,22 @@ dd img max-width: 100% + a + //font-weight: 700 + text-decoration: underline + + a:visited + color: blueviolet + a.button border-radius: 2px + text-decoration: none + + &:visited + color: white a.issue - margin-left: 20px + margin-left: 0px .fixed footer position: fixed @@ -1340,4 +1359,4 @@ $feature-box-div-margin-bottom: 40px // // // -// \ No newline at end of file +// diff --git a/_sass/_reset.sass b/_sass/_reset.sass index 9f4a43a68e..2a8bb1b6d2 100755 --- a/_sass/_reset.sass +++ b/_sass/_reset.sass @@ -15,7 +15,7 @@ ul, li ul margin: 0 padding: 0 - + a text-decoration: none diff --git a/docs/admin/addons.md b/docs/admin/addons.md index f2bd18aaa5..1555f8263c 100644 --- a/docs/admin/addons.md +++ b/docs/admin/addons.md @@ -7,18 +7,20 @@ Add-ons extend the functionality of Kubernetes. This page lists some of the available add-ons and links to their respective installation instructions. +Add-ons in each section are sorted alphabetically - the ordering does not imply any preferential status. + ## Networking and Network Policy -* [Weave Net](https://github.com/weaveworks/weave-kube) provides networking and network policy, will carry on working on both sides of a network partition, and does not require an external database. -* [Calico](http://docs.projectcalico.org/v1.5/getting-started/kubernetes/installation/hosted/) is a secure L3 networking and network policy provider. -* [Flannel](https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml) is a overlay network provider that can be used with Kubernetes. +* [Calico](http://docs.projectcalico.org/v1.6/getting-started/kubernetes/installation/hosted/) is a secure L3 networking and network policy provider. * [Canal](https://github.com/tigera/canal/tree/master/k8s-install/kubeadm) unites Flannel and Calico, providing networking and network policy. +* [Flannel](https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml) is a overlay network provider that can be used with Kubernetes. * [Romana](http://romana.io) is a Layer 3 networking solution for pod networks that also supports the [NetworkPolicy API](/docs/user-guide/networkpolicies/). Kubeadm add-on installation details available [here](https://github.com/romana/romana/tree/master/containerize). +* [Weave Net](https://www.weave.works/docs/net/latest/kube-addon/) provides networking and network policy, will carry on working on both sides of a network partition, and does not require an external database. ## Visualization & Control -* [Weave Scope](https://www.weave.works/documentation/scope-latest-installing/#k8s) is a tool for graphically visualizing your containers, pods, services etc. Use it in conjunction with a [Weave Cloud account](https://cloud.weave.works/) or host the UI yourself. * [Dashboard](https://github.com/kubernetes/dashboard#kubernetes-dashboard) is a dashboard web interface for Kubernetes. +* [Weave Scope](https://www.weave.works/documentation/scope-latest-installing/#k8s) is a tool for graphically visualizing your containers, pods, services etc. Use it in conjunction with a [Weave Cloud account](https://cloud.weave.works/) or host the UI yourself. ## Legacy Add-ons diff --git a/docs/admin/authentication.md b/docs/admin/authentication.md index 6819677107..09cd7910e6 100644 --- a/docs/admin/authentication.md +++ b/docs/admin/authentication.md @@ -6,7 +6,8 @@ assignees: - deads2k --- - +* TOC +{:toc} ## Users in Kubernetes @@ -33,7 +34,7 @@ or be treated as an anonymous user. ## Authentication strategies -Kubernetes uses client certificates, bearer tokens, or HTTP basic auth to +Kubernetes uses client certificates, bearer tokens, an authenticating proxy, or HTTP basic auth to authenticate API requests through authentication plugins. As HTTP request are made to the API server plugins attempts to associate the following attributes with the request: @@ -360,6 +361,20 @@ An unsuccessful request would return: HTTP status codes can be used to supply additional error context. + +### Authenticating Proxy + +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 +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. + + ### Keystone Password Keystone authentication is enabled by passing the `--experimental-keystone-url=` @@ -367,6 +382,13 @@ option to the API server during startup. The plugin is implemented in `plugin/pkg/auth/authenticator/password/keystone/keystone.go` and currently uses basic auth to verify used by username and password. +If you have configured self-signed certificates for the Keystone server, +you may need to set the `--experimental-keystone-ca-file=SOMEFILE` option when +starting the Kubernetes API server. If you set the option, the Keystone +server's certificate is verified by one of the authorities in the +`experimental-keystone-ca-file`. Otherwise, the certificate is verified by +the host's root Certificate Authority. + For details on how to use keystone to manage projects and users, refer to the [Keystone documentation](http://docs.openstack.org/developer/keystone/). Please note that this plugin is still experimental, under active development, and likely diff --git a/docs/admin/authorization.md b/docs/admin/authorization.md index a72a855cb2..1a86359a92 100644 --- a/docs/admin/authorization.md +++ b/docs/admin/authorization.md @@ -207,6 +207,29 @@ and [enable the API version]( /docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster), with a `--runtime-config=` that includes `rbac.authorization.k8s.io/v1alpha1`. +### Privilege Escalation Prevention and Bootstrapping + +The `rbac.authorization.k8s.io` API group inherently attempts to prevent users +from escalating privileges. Simply put, __a user can't grant permissions they +don't already have even when the RBAC authorizer it disabled__. If "user-1" +does not have the ability to read secrets in "namespace-a", they cannot create +a binding that would grant that permission to themselves or any other user. + +For bootstrapping the first roles, it becomes necessary for someone to get +around these limitations. For the alpha release of RBAC, an API Server flag was +added to allow one user to step around all RBAC authorization and privilege +escalation checks. NOTE: _This is subject to change with future releases._ + +``` +--authorization-rbac-super-user=admin +``` + +Once set the specified super user, in this case "admin", can be used to create +the roles and role bindings to initialize the system. + +This flag is optional and once the initial bootstrapping is performed can be +unset. + ### Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings The RBAC API Group declares four top level types which will be covered in this @@ -417,29 +440,6 @@ subjects: name: system:serviceaccounts ``` -### Privilege Escalation Prevention and Bootstrapping - -The `rbac.authorization.k8s.io` API group inherently attempts to prevent users -from escalating privileges. Simply put, __a user can't grant permissions they -don't already have even when the RBAC authorizer it disabled__. If "user-1" -does not have the ability to read secrets in "namespace-a", they cannot create -a binding that would grant that permission to themselves or any other user. - -For bootstrapping the first roles, it becomes necessary for someone to get -around these limitations. For the alpha release of RBAC, an API Server flag was -added to allow one user to step around all RBAC authorization and privilege -escalation checks. NOTE: _This is subject to change with future releases._ - -``` ---authorization-rbac-super-user=admin -``` - -Once set the specified super user, in this case "admin", can be used to create -the roles and role bindings to initialize the system. - -This flag is optional and once the initial bootstrapping is performed can be -unset. - ## Webhook Mode When specified, mode `Webhook` causes Kubernetes to query an outside REST diff --git a/docs/admin/cluster-management.md b/docs/admin/cluster-management.md index 7781368bc8..97362c4bab 100644 --- a/docs/admin/cluster-management.md +++ b/docs/admin/cluster-management.md @@ -95,13 +95,13 @@ If you are using GCE then you can either enable it while creating a cluster with To configure cluser autoscaler you have to set 3 environment variables: * `KUBE_ENABLE_CLUSTER_AUTOSCALER` - it enables cluster autoscaler if set to true. -* `KUBE_AUTOSCALING_MIN_NODES` - minimum number of nodes in the cluster. -* `KUBE_AUTOSCALING_MAX_NODES` - maximum number of nodes in the cluster. +* `KUBE_AUTOSCALER_MIN_NODES` - minimum number of nodes in the cluster. +* `KUBE_AUTOSCALER_MAX_NODES` - maximum number of nodes in the cluster. Example: ```shell -KUBE_ENABLE_CLUSTER_AUTOSCALER=true KUBE_AUTOSCALING_MIN_NODES=3 KUBE_AUTOSCALING_MAX_NODES=10 NUM_NODES=5 ./cluster/kube-up.sh +KUBE_ENABLE_CLUSTER_AUTOSCALER=true KUBE_AUTOSCALER_MIN_NODES=3 KUBE_AUTOSCALER_MAX_NODES=10 NUM_NODES=5 ./cluster/kube-up.sh ``` On GKE you configure cluster autoscaler either on cluster creation or update or when creating a particular node pool diff --git a/docs/admin/dns.md b/docs/admin/dns.md index cc132201aa..d75acfa093 100644 --- a/docs/admin/dns.md +++ b/docs/admin/dns.md @@ -124,7 +124,7 @@ With v1.3, the following annotations are deprecated: `pod.beta.kubernetes.io/hos ## How do I test if it is working? -### Create a simple Pod to use as a test environment. +### Create a simple Pod to use as a test environment Create a file named busybox.yaml with the following contents: @@ -152,7 +152,7 @@ Then create a pod using this file: kubectl create -f busybox.yaml ``` -### Wait for this pod to go into the running state. +### Wait for this pod to go into the running state You can get its status with: ``` @@ -160,12 +160,13 @@ kubectl get pods busybox ``` You should see: + ``` NAME READY STATUS RESTARTS AGE busybox 1/1 Running 0 ``` -### Validate DNS works +### Validate that DNS is working Once that pod is running, you can exec nslookup in that environment: @@ -185,6 +186,115 @@ Address 1: 10.0.0.1 If you see that, DNS is working correctly. +### Troubleshooting Tips + +If the nslookup command fails, check the following: + +#### Check the local DNS configuration first +Take a look inside the resolv.conf file. (See "Inheriting DNS from the node" and "Known issues" below for more information) + +``` +cat /etc/resolv.conf +``` + +Verify that the search path and name server are set up like the following (note that seach path may vary for different cloud providers): + +``` +search default.svc.cluster.local svc.cluster.local cluster.local google.internal c.gce_project_id.internal +nameserver 10.0.0.10 +options ndots:5 +``` + +#### Quick diagnosis + +Errors such as the following indicate a problem with the kube-dns add-on or associated Services: + +``` +$ kubectl exec busybox -- nslookup kubernetes.default +Server: 10.0.0.10 +Address 1: 10.0.0.10 + +nslookup: can't resolve 'kubernetes.default' +``` + +or + +``` +$ kubectl exec busybox -- nslookup kubernetes.default +Server: 10.0.0.10 +Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local + +nslookup: can't resolve 'kubernetes.default' +``` + +#### Check if the DNS pod is running + +Use the kubectl get pods command to verify that the DNS pod is running. + +``` +kubectl get pods --namespace=kube-system -l k8s-app=kube-dns +``` + +You should see something like: + +``` +NAME READY STATUS RESTARTS AGE +... +kube-dns-v19-ezo1y 3/3 Running 0 1h +... +``` + +If you see that no pod is running or that the pod has failed/completed, the dns add-on may not be deployed by default in your current environment and you will have to deploy it manually. + +#### Check for Errors in the DNS pod + +Use `kubectl logs` command to see logs for the DNS daemons. + +``` +kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c kubedns +kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c dnsmasq +kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c healthz +``` + +See if there is any suspicious log. W, E, F letter at the beginning represent Warning, Error and Failure. Please search for entries that have these as the logging level and use [kubernetes issues](https://github.com/kubernetes/kubernetes/issues) to report unexpected errors. + +#### Is dns service up? + +Verify that the DNS service is up by using the `kubectl get service` command. + +``` +kubectl get svc --namespace=kube-system +``` + +You should see: + +``` +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +... +kube-dns 10.0.0.10 53/UDP,53/TCP 1h +... +``` + +If you have created the service or in the case it should be created by default but it does not appear, see this [debugging services page](http://kubernetes.io/docs/user-guide/debugging-services/) for more information. + +#### Are dns endpoints exposed? + +You can verify that dns endpoints are exposed by using the `kubectl get endpoints` command. + +``` +kubectl get ep kube-dns --namespace=kube-system +``` + +You should see something like: +``` +NAME ENDPOINTS AGE +kube-dns 10.180.3.17:53,10.180.3.17:53 1h +``` + +If you do not see the endpoints, see endpoints section in the [debugging services documentation](http://kubernetes.io/docs/user-guide/debugging-services/). + +For additional Kubernetes DNS examples, see the [cluster-dns examples](https://github.com/kubernetes/kubernetes/tree/master/examples/cluster-dns) in the Kubernetes GitHub repository. + ## Kubernetes Federation (Multiple Zone support) Release 1.3 introduced Cluster Federation support for multi-site @@ -213,8 +323,36 @@ the flag `--cluster-domain=` The Kubernetes cluster DNS server (based off the [SkyDNS](https://github.com/skynetservices/skydns) library) supports forward lookups (A records), service lookups (SRV records) and reverse IP address lookups (PTR records). +## Inheriting DNS from the node +When running a pod, kubelet will prepend the cluster DNS server and search +paths to the node's own DNS settings. If the node is able to resolve DNS names +specific to the larger environment, pods should be able to, also. See "Known +issues" below for a caveat. + +If you don't want this, or if you want a different DNS config for pods, you can +use the kubelet's `--resolv-conf` flag. Setting it to "" means that pods will +not inherit DNS. Setting it to a valid file path means that kubelet will use +this file instead of `/etc/resolv.conf` for DNS inheritance. + +## Known issues +Kubernetes installs do not configure the nodes' resolv.conf files to use the +cluster DNS by default, because that process is inherently distro-specific. +This should probably be implemented eventually. + +Linux's libc is impossibly stuck ([see this bug from +2005](https://bugzilla.redhat.com/show_bug.cgi?id=168253)) with limits of just +3 DNS `nameserver` records and 6 DNS `search` records. Kubernetes needs to +consume 1 `nameserver` record and 3 `search` records. This means that if a +local installation already uses 3 `nameserver`s or uses more than 3 `search`es, +some of those settings will be lost. As a partial workaround, the node can run +`dnsmasq` which will provide more `nameserver` entries, but not more `search` +entries. You can also use kubelet's `--resolv-conf` flag. + +If you are using Alpine version 3.3 or earlier as your base image, dns may not +work properly owing to a known issue with Alpine. Check [here](https://github.com/kubernetes/kubernetes/issues/30215) +for more information. ## References -- [Docs for the DNS cluster addon](http://releases.k8s.io/{{page.githubbranch}}/build/kube-dns/README.md) +- [Docs for the DNS cluster addon](http://releases.k8s.io/{{page.githubbranch}}/build-tools/kube-dns/README.md) diff --git a/docs/admin/high-availability/index.md b/docs/admin/high-availability/index.md index efe6ddac4b..ad78270e4a 100644 --- a/docs/admin/high-availability/index.md +++ b/docs/admin/high-availability/index.md @@ -100,16 +100,15 @@ for `${NODE_IP}` on each machine. #### Validating your cluster -Once you copy this into all three nodes, you should have a clustered etcd set up. You can validate with - +Once you copy this into all three nodes, you should have a clustered etcd set up. You can validate on master with ```shell -etcdctl member list +kubectl exec < pod_name > etcdctl member list ``` and ```shell -etcdctl cluster-health +kubectl exec < pod_name > etcdctl cluster-health ``` You can also validate that this is working with `etcdctl set foo bar` on one node, and `etcdctl get foo` diff --git a/docs/admin/network-plugins.md b/docs/admin/network-plugins.md index 8cfeb658c9..6c5f354423 100644 --- a/docs/admin/network-plugins.md +++ b/docs/admin/network-plugins.md @@ -36,15 +36,21 @@ Place plugins in `network-plugin-dir/plugin-name/plugin-name`, i.e if you have a ### CNI -The CNI plugin is selected by passing Kubelet the `--network-plugin=cni` command-line option. Kubelet reads a file from `--cni-conf-dir` (default `/etc/cni/net.d`) and uses the CNI configuration from that file to set up each pod's network. The CNI configuration file must match the [CNI specification](https://github.com/containernetworking/cni/blob/master/SPEC.md), and any required CNI plugins referenced by the configuration must be present in `--cni-bin-dir` (default `/opt/cni/bin`). +The CNI plugin is selected by passing Kubelet the `--network-plugin=cni` command-line option. Kubelet reads a file from `--cni-conf-dir` (default `/etc/cni/net.d`) and uses the CNI configuration from that file to set up each pod's network. The CNI configuration file must match the [CNI specification](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration), and any required CNI plugins referenced by the configuration must be present in `--cni-bin-dir` (default `/opt/cni/bin`). If there are multiple CNI configuration files in the directory, the first one in lexicographic order of file name is used. -In addition to the CNI plugin specified by the configuration file, Kubernetes requires the standard CNI `lo` plugin, at minimum version 0.2.0 +In addition to the CNI plugin specified by the configuration file, Kubernetes requires the standard CNI [`lo`](https://github.com/containernetworking/cni/blob/master/plugins/main/loopback/loopback.go) plugin, at minimum version 0.2.0 + +Limitation: Due to [#31307](https://github.com/kubernetes/kubernetes/issues/31307), `HostPort` won't work with CNI networking plugin at the moment. That means all `hostPort` attribute in pod would be simply ignored. ### kubenet -The Linux-only kubenet plugin provides functionality similar to the `--configure-cbr0` kubelet command-line option. It creates a Linux bridge named `cbr0` and creates a veth pair for each pod with the host end of each pair connected to `cbr0`. The pod end of the pair is assigned an IP address allocated from a range assigned to the node either through configuration or by the controller-manager. `cbr0` is assigned an MTU matching the smallest MTU of an enabled normal interface on the host. The kubenet plugin is currently mutually exclusive with, and will eventually replace, the --configure-cbr0 option. It is also currently incompatible with the flannel experimental overlay. +Kubenet is a very basic, simple network plugin, on Linux only. It does not, of itself, implement more advanced features like cross-node networking or network policy. It is typically used together with a cloud provider that sets up routing rules for communication between nodes, or in single-node environments. + +Kubenet creates a Linux bridge named `cbr0` and creates a veth pair for each pod with the host end of each pair connected to `cbr0`. The pod end of the pair is assigned an IP address allocated from a range assigned to the node either through configuration or by the controller-manager. `cbr0` is assigned an MTU matching the smallest MTU of an enabled normal interface on the host. + +The kubenet plugin is mutually exclusive with the --configure-cbr0 option. The plugin requires a few things: @@ -72,4 +78,4 @@ This option is provided to the network-plugin; currently **only kubenet supports * `--network-plugin=exec` specifies that we use the `exec` plugin, with executables located in `--network-plugin-dir`. * `--network-plugin=cni` specifies that we use the `cni` network plugin with actual CNI plugin binaries located in `--cni-bin-dir` (default `/opt/cni/bin`) and CNI plugin configuration located in `--cni-conf-dir` (default `/etc/cni/net.d`). * `--network-plugin=kubenet` specifies that we use the `kubenet` network plugin with CNI `bridge` and `host-local` plugins placed in `/opt/cni/bin` or `network-plugin-dir`. -* `--network-plugin-mtu=9001` specifies the MTU to use, currently only used by the `kubenet` network plugin. \ No newline at end of file +* `--network-plugin-mtu=9001` specifies the MTU to use, currently only used by the `kubenet` network plugin. diff --git a/docs/admin/networking.md b/docs/admin/networking.md index 2acbf062d4..28c259a5f7 100644 --- a/docs/admin/networking.md +++ b/docs/admin/networking.md @@ -1,4 +1,4 @@ ---- +--- assignees: - lavalamp - thockin @@ -83,7 +83,7 @@ talk to other VMs in your project. This is the same basic model. Until now this document has talked about containers. In reality, Kubernetes applies IP addresses at the `Pod` scope - containers within a `Pod` share their network namespaces - including their IP address. This means that containers -within a `Pod` can all reach each other’s ports on `localhost`. This does imply +within a `Pod` can all reach each other's ports on `localhost`. This does imply that containers within a `Pod` must coordinate port usage, but this is no different than processes in a VM. We call this the "IP-per-pod" model. This is implemented in Docker as a "pod container" which holds the network namespace @@ -100,8 +100,19 @@ existence or non-existence of host ports. There are a number of ways that this network model can be implemented. This document is not an exhaustive study of the various methods, but hopefully serves as an introduction to various technologies and serves as a jumping-off point. -If some techniques become vastly preferable to others, we might detail them more -here. + +The following networking options are sorted alphabetically - the order does not +imply any preferential status. + +### Contiv + +[Contiv](https://github.com/contiv/netplugin) provides configurable networking (native l3 using BGP, overlay using vxlan, classic l2, or Cisco-SDN/ACI) for various use cases. [Contiv](http://contiv.io) is all open sourced. + +### Flannel + +[Flannel](https://github.com/coreos/flannel#flannel) is a very simple overlay +network that satisfies the Kubernetes requirements. Many +people have reported success with Flannel and Kubernetes. ### Google Compute Engine (GCE) @@ -158,32 +169,15 @@ Follow the "With Linux Bridge devices" section of [this very nice tutorial](http://blog.oddbit.com/2014/08/11/four-ways-to-connect-a-docker/) from Lars Kellogg-Stedman. -### Weave Net from Weaveworks - -[Weave Net](https://www.weave.works/products/weave-net/) is a -resilient and simple to use network for Kubernetes and its hosted applications. -Weave Net runs as a [CNI plug-in](https://www.weave.works/docs/net/latest/cni-plugin/) -or stand-alone. In either version, it doesn’t require any configuration or extra code -to run, and in both cases, the network provides one IP address per pod - as is standard for Kubernetes. - - -### Flannel - -[Flannel](https://github.com/coreos/flannel#flannel) is a very simple overlay -network that satisfies the Kubernetes requirements. It installs in minutes and -should get you up and running if the above techniques are not working. Many -people have reported success with Flannel and Kubernetes. - ### OpenVSwitch [OpenVSwitch](/docs/admin/ovs-networking) is a somewhat more mature but also complicated way to build an overlay network. This is endorsed by several of the "Big Shops" for networking. - ### Project Calico -[Project Calico](https://github.com/projectcalico/calico-containers/blob/master/docs/cni/kubernetes/README.md) is an open source container networking provider and network policy engine. +[Project Calico](http://docs.projectcalico.org/) is an open source container networking provider and network policy engine. Calico provides a highly scalable networking and network policy solution for connecting Kubernetes pods based on the same IP networking principles as the internet. Calico can be deployed without encapsulation or overlays to provide high-performance, high-scale data center networking. Calico also provides fine-grained, intent based network security policy for Kubernetes pods via its distributed firewall. @@ -193,9 +187,13 @@ Calico can also be run in policy enforcement mode in conjunction with other netw [Romana](http://romana.io) is an open source network and security automation solution that lets you deploy Kubernetes without an overlay network. Romana supports Kubernetes [Network Policy](/docs/user-guide/networkpolicies/) to provide isolation across network namespaces. -### Contiv +### Weave Net from Weaveworks -[Contiv](https://github.com/contiv/netplugin) provides configurable networking (native l3 using BGP, overlay using vxlan, classic l2, or Cisco-SDN/ACI) for various use cases. [Contiv](http://contiv.io) is all open sourced. +[Weave Net](https://www.weave.works/products/weave-net/) is a +resilient and simple to use network for Kubernetes and its hosted applications. +Weave Net runs as a [CNI plug-in](https://www.weave.works/docs/net/latest/cni-plugin/) +or stand-alone. In either version, it doesn't require any configuration or extra code +to run, and in both cases, the network provides one IP address per pod - as is standard for Kubernetes. ## Other reading diff --git a/docs/admin/node.md b/docs/admin/node.md index e7dbbba987..78ef3c4b2e 100644 --- a/docs/admin/node.md +++ b/docs/admin/node.md @@ -27,7 +27,7 @@ pieces of information: The usage of these fields varies depending on your cloud provider or bare metal configuration. -* HostName: Generally not used +* HostName: The hostname as reported by the node's kernel. Can be overridden via the kubelet `--hostname-override` parameter. * ExternalIP: Generally the IP address of the node that is externally routable (available from outside the cluster) diff --git a/docs/api.md b/docs/api.md index aa9aea1d7f..9ea627721e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -95,46 +95,3 @@ DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets Other extensions resources can be enabled by setting runtime-config on apiserver. runtime-config accepts comma separated values. For ex: to disable deployments and jobs, set `--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false` - -## v1beta1, v1beta2, and v1beta3 are deprecated; please move to v1 ASAP - -As of June 4, 2015, the Kubernetes v1 API has been enabled by default. The v1beta1 and v1beta2 APIs were deleted on June 1, 2015. v1beta3 is planned to be deleted on July 6, 2015. - -### v1 conversion tips (from v1beta3) - -We're working to convert all documentation and examples to v1. Use `kubectl create --validate` in order to validate your json or yaml against our Swagger spec. - -Changes to services are the most significant difference between v1beta3 and v1. - -* The `service.spec.portalIP` property is renamed to `service.spec.clusterIP`. -* The `service.spec.createExternalLoadBalancer` property is removed. Specify `service.spec.type: "LoadBalancer"` to create an external load balancer instead. -* The `service.spec.publicIPs` property is deprecated and now called `service.spec.deprecatedPublicIPs`. This property will be removed entirely when v1beta3 is removed. The vast majority of users of this field were using it to expose services on ports on the node. Those users should specify `service.spec.type: "NodePort"` instead. Read [External Services](/docs/user-guide/services/#external-services) for more info. If this is not sufficient for your use case, please file an issue or contact @thockin. - -Some other difference between v1beta3 and v1: - -* The `pod.spec.containers[*].privileged` and `pod.spec.containers[*].capabilities` properties are now nested under the `pod.spec.containers[*].securityContext` property. See [Security Contexts](/docs/user-guide/security-context). -* The `pod.spec.host` property is renamed to `pod.spec.nodeName`. -* The `endpoints.subsets[*].addresses.IP` property is renamed to `endpoints.subsets[*].addresses.ip`. -* The `pod.status.containerStatuses[*].state.termination` and `pod.status.containerStatuses[*].lastState.termination` properties are renamed to `pod.status.containerStatuses[*].state.terminated` and `pod.status.containerStatuses[*].lastState.terminated` respectively. -* The `pod.status.Condition` property is renamed to `pod.status.conditions`. -* The `status.details.id` property is renamed to `status.details.name`. - -### v1beta3 conversion tips (from v1beta1/2) - -Some important differences between v1beta1/2 and v1beta3: - -* The resource `id` is now called `name`. -* `name`, `labels`, `annotations`, and other metadata are now nested in a map called `metadata` -* `desiredState` is now called `spec`, and `currentState` is now called `status` -* `/minions` has been moved to `/nodes`, and the resource has kind `Node` -* The namespace is required (for all namespaced resources) and has moved from a URL parameter to the path: `/api/v1beta3/namespaces/{namespace}/{resource_collection}/{resource_name}`. If you were not using a namespace before, use `default` here. -* The names of all resource collections are now lower cased - instead of `replicationControllers`, use `replicationcontrollers`. -* To watch for changes to a resource, open an HTTP or Websocket connection to the collection query and provide the `?watch=true` query parameter along with the desired `resourceVersion` parameter to watch from. -* The `labels` query parameter has been renamed to `labelSelector`. -* The `fields` query parameter has been renamed to `fieldSelector`. -* The container `entrypoint` has been renamed to `command`, and `command` has been renamed to `args`. -* Container, volume, and node resources are expressed as nested maps (e.g., `resources{cpu:1}`) rather than as individual fields, and resource values support [scaling suffixes](/docs/user-guide/compute-resources/#specifying-resource-quantities) rather than fixed scales (e.g., milli-cores). -* Restart policy is represented simply as a string (e.g., `"Always"`) rather than as a nested map (`always{}`). -* Pull policies changed from `PullAlways`, `PullNever`, and `PullIfNotPresent` to `Always`, `Never`, and `IfNotPresent`. -* The volume `source` is inlined into `volume` rather than nested. -* Host volumes have been changed from `hostDir` to `hostPath` to better reflect that they can be files or directories. \ No newline at end of file diff --git a/docs/contribute/create-pull-request.md b/docs/contribute/create-pull-request.md index e79fe22c96..7f42bfb125 100644 --- a/docs/contribute/create-pull-request.md +++ b/docs/contribute/create-pull-request.md @@ -14,10 +14,9 @@ repository. This page shows how to create a pull request. 1. Create a [GitHub account](https://github.com){: target="_blank"}. 1. Sign the -[Google Contributor License Agreement](https://cla.developers.google.com/about/google-individual){: target="_blank"}. +[Linux Foundation Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}. -1. Sign the -[Linux Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}. +Documentation will be published under the [CC BY SA 4.0](https://github.com/kubernetes/kubernetes.github.io/blob/master/LICENSE) license. {% endcapture %} diff --git a/docs/contribute/page-templates.md b/docs/contribute/page-templates.md index 5bea261e3c..4b19cde39b 100644 --- a/docs/contribute/page-templates.md +++ b/docs/contribute/page-templates.md @@ -1,4 +1,7 @@ --- +redirect_from: + - /docs/templatedemos/ + - /docs/templatedemos.html --- - - + + + + + + + + + + + + + + + + + + + + + + + + + Docker + Kubelt + + + Layer 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/tutorials/stateful-application/gce-volume.yaml b/docs/tutorials/stateful-application/gce-volume.yaml new file mode 100644 index 0000000000..ddb9ecc3ce --- /dev/null +++ b/docs/tutorials/stateful-application/gce-volume.yaml @@ -0,0 +1,12 @@ +apiVersion: v1 +kind: PersistentVolume +metadata: + name: mysql-pv +spec: + capacity: + storage: 20Gi + accessModes: + - ReadWriteOnce + gcePersistentDisk: + pdName: mysql-disk + fsType: ext4 diff --git a/docs/tutorials/stateful-application/mysql-deployment.yaml b/docs/tutorials/stateful-application/mysql-deployment.yaml new file mode 100644 index 0000000000..3b2aa22f6c --- /dev/null +++ b/docs/tutorials/stateful-application/mysql-deployment.yaml @@ -0,0 +1,51 @@ +apiVersion: v1 +kind: Service +metadata: + name: mysql +spec: + ports: + - port: 3306 + selector: + app: mysql + clusterIP: None +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: mysql-pv-claim +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 20Gi +--- +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: mysql +spec: + strategy: + type: Recreate + template: + metadata: + labels: + app: mysql + spec: + containers: + - image: mysql:5.6 + name: mysql + env: + # Use secret in real usage + - name: MYSQL_ROOT_PASSWORD + value: password + ports: + - containerPort: 3306 + name: mysql + volumeMounts: + - name: mysql-persistent-storage + mountPath: /var/lib/mysql + volumes: + - name: mysql-persistent-storage + persistentVolumeClaim: + claimName: mysql-pv-claim diff --git a/docs/tutorials/stateful-application/run-stateful-application.md b/docs/tutorials/stateful-application/run-stateful-application.md new file mode 100644 index 0000000000..443d9cdea5 --- /dev/null +++ b/docs/tutorials/stateful-application/run-stateful-application.md @@ -0,0 +1,220 @@ +--- +--- + +{% capture overview %} + +This page shows you how to run a single-instance stateful application +in Kubernetes using a PersistentVolume and a Deployment. The +application is MySQL. + +{% endcapture %} + + +{% capture objectives %} + +* Create a PersistentVolume referencing a disk in your environment. +* Create a MySQL Deployment. +* Expose MySQL to other pods in the cluster at a known DNS name. + +{% endcapture %} + + +{% capture prerequisites %} + +* {% include task-tutorial-prereqs.md %} + +* For data persistence we will create a Persistent Volume that + references a disk in your + environment. See + [here](/docs/user-guide/persistent-volumes/#types-of-persistent-volumes) for + the types of environments supported. This Tutorial will demonstrate + `GCEPersistentDisk` but any type will work. `GCEPersistentDisk` + volumes only work on Google Compute Engine. + +{% endcapture %} + + +{% capture lessoncontent %} + +### Set up a disk in your environment + +You can use any type of persistent volume for your stateful app. See +[Types of Persistent Volumes](/docs/user-guide/persistent-volumes/#types-of-persistent-volumes) +for a list of supported environment disks. For Google Compute Engine, run: + +``` +gcloud compute disks create --size=20GB mysql-disk +``` + +Next create a PersistentVolume that points to the `mysql-disk` +disk just created. Here is a configuration file for a PersistentVolume +that points to the Compute Engine disk above: + +{% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %} + +Notice that the `pdName: mysql-disk` line matches the name of the disk +in the Compute Engine environment. See the +[Persistent Volumes](/docs/user-guide/persistent-volumes/) +for details on writing a PersistentVolume configuration file for other +environments. + +Create the persistent volume: + +``` +kubectl create -f http://k8s.io/docs/tutorials/stateful-application/gce-volume.yaml +``` + + +### Deploy MySQL + +You can run a stateful application by creating a Kubernetes Deployment +and connecting it to an existing PersistentVolume using a +PersistentVolumeClaim. For example, this YAML file describes a +Deployment that runs MySQL and references the PersistentVolumeClaim. The file +defines a volume mount for /var/lib/mysql, and then creates a +PersistentVolumeClaim that looks for a 20G volume. This claim is +satisfied by any volume that meets the requirements, in this case, the +volume created above. + +Note: The password is defined in the config yaml, and this is insecure. See +[Kubernetes Secrets](/docs/user-guide/secrets/) +for a secure solution. + +{% include code.html language="yaml" file="mysql-deployment.yaml" ghlink="/docs/tutorials/stateful-application/mysql-deployment.yaml" %} + +1. Deploy the contents of the YAML file: + + kubectl create -f http://k8s.io/docs/tutorials/stateful-application/mysql-deployment.yaml + +1. Display information about the Deployment: + + kubectl describe deployment mysql + + Name: mysql + Namespace: default + CreationTimestamp: Tue, 01 Nov 2016 11:18:45 -0700 + Labels: app=mysql + Selector: app=mysql + Replicas: 1 updated | 1 total | 0 available | 1 unavailable + StrategyType: Recreate + MinReadySeconds: 0 + OldReplicaSets: + NewReplicaSet: mysql-63082529 (1/1 replicas created) + Events: + FirstSeen LastSeen Count From SubobjectPath Type Reason Message + --------- -------- ----- ---- ------------- -------- ------ ------- + 33s 33s 1 {deployment-controller } Normal ScalingReplicaSet Scaled up replica set mysql-63082529 to 1 + +1. List the pods created by the Deployment: + + kubectl get pods -l app=mysql + + NAME READY STATUS RESTARTS AGE + mysql-63082529-2z3ki 1/1 Running 0 3m + +1. Inspect the Persistent Volume: + + kubectl describe pv mysql-pv + + Name: mysql-pv + Labels: + Status: Bound + Claim: default/mysql-pv-claim + Reclaim Policy: Retain + Access Modes: RWO + Capacity: 20Gi + Message: + Source: + Type: GCEPersistentDisk (a Persistent Disk resource in Google Compute Engine) + PDName: mysql-disk + FSType: ext4 + Partition: 0 + ReadOnly: false + No events. + +1. Inspect the PersistentVolumeClaim: + + kubectl describe pvc mysql-pv-claim + + Name: mysql-pv-claim + Namespace: default + Status: Bound + Volume: mysql-pv + Labels: + Capacity: 20Gi + Access Modes: RWO + No events. + +### Accessing the MySQL instance + +The preceding YAML file creates a service that +allows other Pods in the cluster to access the database. The Service option +`clusterIP: None` lets the Service DNS name resolve directly to the +Pod's IP address. This is optimal when you have only one Pod +behind a Service and you don't intend to increase the number of Pods. + +Run a MySQL client to connect to the server: + +``` +kubectl run -it --rm --image=mysql:5.6 mysql-client -- mysql -h mysql -ppassword +``` + +This command creates a new Pod in the cluster running a mysql client +and connects it to the server through the Service. If it connects, you +know your stateful MySQL database is up and running. + +``` +Waiting for pod default/mysql-client-274442439-zyp6i to be running, status is Pending, pod ready: false +If you don't see a command prompt, try pressing enter. + +mysql> +``` + +### Updating + +The image or any other part of the Deployment can be updated as usual +with the `kubectl apply` command. Here are some precautions that are +specific to stateful apps: + +* Don't scale the app. This setup is for single-instance apps + only. The underlying PersistentVolume can only be mounted to one + Pod. For clustered stateful apps, see the + [StatefulSet documentation](/docs/user-guide/petset/). +* Use `strategy:` `type: Recreate` in the Deployment configuration + YAML file. This instructs Kubernetes to _not_ use rolling + updates. Rolling updates will not work, as you cannot have more than + one Pod running at a time. The `Recreate` strategy will stop the + first pod before creating a new one with the updated configuration. + +### Deleting a deployment + +Delete the deployed objects by name: + +``` +kubectl delete deployment,svc mysql +kubectl delete pvc mysql-pv-claim +kubectl delete pv mysql-pv +``` + +Also, if you are using Compute Engine disks: + +``` +gcloud compute disks delete mysql-disk +``` + +{% endcapture %} + + +{% capture whatsnext %} + +* Learn more about [Deployment objects](/docs/user-guide/deployments/). + +* Learn more about [Deploying applications](/docs/user-guide/deploying-applications/) + +* [kubectl run documentation](/docs/user-guide/kubectl/kubectl_run/) + +* [Volumes](/docs/user-guide/volumes/) and [Persistent Volumes](/docs/user-guide/persistent-volumes/) + +{% endcapture %} + +{% include templates/tutorial.md %} diff --git a/docs/user-guide/accessing-the-cluster.md b/docs/user-guide/accessing-the-cluster.md index 6f78ab5293..63134b4909 100644 --- a/docs/user-guide/accessing-the-cluster.md +++ b/docs/user-guide/accessing-the-cluster.md @@ -129,7 +129,7 @@ To use it, * Write an application atop of the client-go clients. Note that client-go defines its own API objects, so if needed, please import API definitions from client-go rather than from the main repository, e.g., `import "k8s.io/client-go/1.4/pkg/api/v1"` is correct. The Go client can use the same [kubeconfig file](/docs/user-guide/kubeconfig-file) -as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/examples/out-of-cluster.go): +as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/blob/master/examples/out-of-cluster/main.go): ```golang import ( @@ -183,7 +183,8 @@ From within a pod the recommended ways to connect to API are: in any container of the pod can access it. See this [example of using kubectl proxy in a pod](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/kubectl-container/). - use the Go client library, and create a client using the `client.NewInCluster()` factory. - This handles locating and authenticating to the apiserver. [example](https://github.com/kubernetes/client-go/examples/in-cluster.go) + This handles locating and authenticating to the apiserver. See this [example of using Go client + library in a pod](https://github.com/kubernetes/client-go/blob/master/examples/in-cluster/main.go). In each case, the credentials of the pod are used to communicate securely with the apiserver. diff --git a/docs/user-guide/configuring-containers.md b/docs/user-guide/configuring-containers.md index 6b7b447289..99dc823375 100644 --- a/docs/user-guide/configuring-containers.md +++ b/docs/user-guide/configuring-containers.md @@ -12,7 +12,7 @@ assignees: In addition to the imperative-style commands, such as `kubectl run` and `kubectl expose`, described [elsewhere](/docs/user-guide/quick-start), Kubernetes supports declarative configuration. Oftentimes, configuration files are preferable to imperative commands, since they can be checked into version control and changes to the files can be code reviewed, which is especially important for more complex configurations, producing a more robust, reliable and archival system. -In the declarative style, all configuration is stored in YAML or JSON configuration files using Kubernetes's API resource schemas as the configuration schemas. `kubectl` can create, update, delete, and get API resources. The `apiVersion` (currently 'v1'?), resource `kind`, and resource `name` are used by `kubectl` to construct the appropriate API path to invoke for the specified operation. +In the declarative style, all configuration is stored in YAML or JSON configuration files using Kubernetes's API resource schemas as the configuration schemas. `kubectl` can create, update, delete, and get API resources. The `apiVersion` (currently `v1`?), resource `kind`, and resource `name` are used by `kubectl` to construct the appropriate API path to invoke for the specified operation. ## Launching a container using a configuration file diff --git a/docs/user-guide/scheduled-jobs.md b/docs/user-guide/cron-jobs.md similarity index 56% rename from docs/user-guide/scheduled-jobs.md rename to docs/user-guide/cron-jobs.md index b96014a6d1..6d88997cb3 100644 --- a/docs/user-guide/scheduled-jobs.md +++ b/docs/user-guide/cron-jobs.md @@ -9,16 +9,22 @@ assignees: * TOC {:toc} -## What is a _Scheduled Job_? +## What is a _Cron Job_? -A _Scheduled Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely: +A _Cron Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely: * Once at a specified point in time * Repeatedly at a specified point in time -One ScheduledJob object is like one line of a _crontab_ (cron table) file. It runs a job periodically +One CronJob object is like one line of a _crontab_ (cron table) file. It runs a job periodically on a given schedule, written in [Cron](https://en.wikipedia.org/wiki/Cron) format. +**Note:**: The question mark (`?`) in the schedule has the same meaning as an asterisk `*`, +that is, it stands for any of available value for a given field. + +**Note:**: ScheduledJob resource was introduced in Kubernetes version 1.4, but starting +from version 1.5 its current name is CronJob. + A typical use case is: * Schedule a job execution at a given point in time. @@ -26,41 +32,41 @@ A typical use case is: ### Prerequisites -You need a working Kubernetes cluster at version >= 1.4, with batch/v2alpha1 API turned on by passing -`--runtime-config=batch/v2alpha1` while bringing up the API server (see [Turn on or off an API version -for your cluster](/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster) for -more). You cannot use Scheduled Jobs on a hosted Kubernetes provider that has disabled alpha resources. +You need a working Kubernetes cluster at version >= 1.4 (for ScheduledJob), >= 1.5 (for CronJobs), +with batch/v2alpha1 API turned on by passing `--runtime-config=batch/v2alpha1` while bringing up +the API server (see [Turn on or off an API version for your cluster](/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster) +for more). You cannot use Cron Jobs on a hosted Kubernetes provider that has disabled alpha resources. -## Creating a Scheduled Job +## Creating a Cron Job -Here is an example Scheduled Job. Every minute, it runs a simple job to print current time and then say +Here is an example Cron Job. Every minute, it runs a simple job to print current time and then say hello. -{% include code.html language="yaml" file="sj.yaml" ghlink="/docs/user-guide/sj.yaml" %} +{% include code.html language="yaml" file="cronjob.yaml" ghlink="/docs/user-guide/cronjob.yaml" %} -Run the example scheduled job by downloading the example file and then running this command: +Run the example cron job by downloading the example file and then running this command: ```shell -$ kubectl create -f ./sj.yaml -scheduledjob "hello" created +$ kubectl create -f ./cronjob.yaml +cronjob "hello" created ``` -Alternatively, use `kubectl run` to create a scheduled job without writing full config: +Alternatively, use `kubectl run` to create a cron job without writing full config: ```shell -$ kubectl run hello --schedule="0/1 * * * ?" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster" -scheduledjob "hello" created +$ kubectl run hello --schedule="*/1 * * * *" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster" +cronjob "hello" created ``` -After creating the scheduled job, get its status using this command: +After creating the cron job, get its status using this command: ```shell -$ kubectl get scheduledjob hello +$ kubectl get cronjob hello NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE -hello 0/1 * * * ? False 0 +hello */1 * * * * False 0 ``` -As you can see above, there's no active job yet, and no job has been scheduled, either. +As you can see above, there's no active job yet, and no job has been scheduled, either. Watch for the job to be created in around one minute: @@ -70,16 +76,16 @@ NAME DESIRED SUCCESSFUL AGE hello-4111706356 1 1 2s ``` -Now you've seen one running job scheduled by "hello". We can stop watching it and get the scheduled job again: +Now you've seen one running job scheduled by "hello". We can stop watching it and get the cron job again: ```shell -$ kubectl get scheduledjob hello +$ kubectl get cronjob hello NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE -hello 0/1 * * * ? False 0 Mon, 29 Aug 2016 14:34:00 -0700 +hello */1 * * * * False 0 Mon, 29 Aug 2016 14:34:00 -0700 ``` You should see that "hello" successfully scheduled a job at the time specified in `LAST-SCHEDULE`. There are -currently 0 active jobs, meaning that the job that's scheduled is completed or failed. +currently 0 active jobs, meaning that the job that's scheduled is completed or failed. Now, find the pods created by the job last scheduled and view the standard output of one of the pods. Note that your job name and pod name would be different. @@ -96,17 +102,17 @@ Mon Aug 29 21:34:09 UTC 2016 Hello from the Kubernetes cluster ``` -## Deleting a Scheduled Job +## Deleting a Cron Job -Once you don't need a scheduled job anymore, simply delete it with `kubectl`: +Once you don't need a cron job anymore, simply delete it with `kubectl`: ```shell -$ kubectl delete scheduledjob hello -scheduledjob "hello" deleted +$ kubectl delete cronjob hello +cronjob "hello" deleted ``` This stops new jobs from being created. However, running jobs won't be stopped, and no jobs or their pods will -be deleted. To clean up those jobs and pods, you need to list all jobs created by the scheduled job, and delete them all: +be deleted. To clean up those jobs and pods, you need to list all jobs created by the cron job, and delete them all: ```shell $ kubectl get jobs @@ -121,34 +127,34 @@ job "hello-1202039034" deleted ... ``` -Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by scheduled -job "hello" will be prefixed "hello-". You can delete them at once with `kubectl delete jobs --all`, if you want to +Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by cron +job "hello" will be prefixed "hello-". You can delete them at once with `kubectl delete jobs --all`, if you want to delete all jobs in the current namespace (not just the ones created by "hello".) -## Scheduled Job Limitations +## Cron Job Limitations -A scheduled job creates a job object _about_ once per execution time of its schedule. We say "about" because there +A cron job creates a job object _about_ once per execution time of its schedule. We say "about" because there are certain circumstances where two jobs might be created, or no job might be created. We attempt to make these rare, but do not completely prevent them. Therefore, jobs should be _idempotent_. The job is responsible for retrying pods, parallelism among pods it creates, and determining the success or failure -of the set of pods. A scheduled job does not examine pods at all. +of the set of pods. A cron job does not examine pods at all. -## Writing a Scheduled Job Spec +## Writing a Cron Job Spec -As with all other Kubernetes configs, a scheduled job needs `apiVersion`, `kind`, and `metadata` fields. For general -information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), +As with all other Kubernetes configs, a cron job needs `apiVersion`, `kind`, and `metadata` fields. For general +information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), [configuring containers](/docs/user-guide/configuring-containers), and [using kubectl to manage resources](/docs/user-guide/working-with-resources) documents. -A scheduled job also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status). +A cron job also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status). -**Note:** All modifications to a scheduled job, especially its `.spec`, will be applied only to the next run. +**Note:** All modifications to a cron job, especially its `.spec`, will be applied only to the next run. -### Schedule +### Schedule The `.spec.schedule` is a required field of the `.spec`. It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format -string, e.g. `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed. +string, e.g. `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed. ### Job Template @@ -159,22 +165,22 @@ as a [Job](/docs/user-guide/jobs), except it is nested and does not have an `api ### Starting Deadline Seconds The `.spec.startingDeadlineSeconds` field is optional. It stands for the deadline (in seconds) for starting the job -if it misses its scheduled time for any reason. Missed jobs executions will be counted as failed ones. If not specified, -there's no deadline. +if it misses its scheduled time for any reason. Missed jobs executions will be counted as failed ones. If not specified, +there's no deadline. ### Concurrency Policy The `.spec.concurrencyPolicy` field is also optional. It specifies how to treat concurrent executions of a job -created by this scheduled job. Only one of the following concurrent policies may be specified: +created by this cron job. Only one of the following concurrent policies may be specified: * `Allow` (default): allows concurrently running jobs * `Forbid`: forbids concurrent runs, skipping next run if previous hasn't finished yet * `Replace`: cancels currently running job and replaces it with a new one -Note that concurrency policy only applies to the jobs created by the same scheduled job. If there are multiple -scheduled jobs, their respective jobs are always allowed to run concurrently. +Note that concurrency policy only applies to the jobs created by the same cron job. If there are multiple +cron jobs, their respective jobs are always allowed to run concurrently. ### Suspend -The `.spec.suspend` field is also optional. If set to `true`, all subsequent executions will be suspended. It does not -apply to already started executions. Defaults to false. +The `.spec.suspend` field is also optional. If set to `true`, all subsequent executions will be suspended. It does not +apply to already started executions. Defaults to false. diff --git a/docs/user-guide/sj.yaml b/docs/user-guide/cronjob.yaml similarity index 88% rename from docs/user-guide/sj.yaml rename to docs/user-guide/cronjob.yaml index 1b22b7f340..cdb1c469a1 100644 --- a/docs/user-guide/sj.yaml +++ b/docs/user-guide/cronjob.yaml @@ -1,9 +1,9 @@ apiVersion: batch/v2alpha1 -kind: ScheduledJob +kind: CronJob metadata: name: hello spec: - schedule: 0/1 * * * ? + schedule: "*/1 * * * *" jobTemplate: spec: template: diff --git a/docs/user-guide/federation/federated-ingress.md b/docs/user-guide/federation/federated-ingress.md index 87965a3fc7..6198de1817 100644 --- a/docs/user-guide/federation/federated-ingress.md +++ b/docs/user-guide/federation/federated-ingress.md @@ -64,12 +64,12 @@ healthy backend service endpoint at all times, even in the event of pod, cluster, availability zone or regional outages. -Note that in the - case of Google Cloud, the logical L7 load balancer is not a single physical device (which - would present both a single point of failure, and a single global - network routing choke point), but rather a [truly global, highly available - load balancing managed service](https://cloud.google.com/load-balancing/), - globally reachable via a single, static IP address. +Note that in the case of Google Cloud, the logical L7 load balancer is +not a single physical device (which would present both a single point +of failure, and a single global network routing choke point), but +rather a +[truly global, highly available load balancing managed service](https://cloud.google.com/load-balancing/), +globally reachable via a single, static IP address. Clients inside your federated Kubernetes clusters (i.e. Pods) will be automatically routed to the cluster-local shard of the Federated Service @@ -86,13 +86,13 @@ You can create a federated ingress in any of the usual ways, for example using k ``` shell kubectl --context=federation-cluster create -f myingress.yaml ``` - +For example ingress YAML configurations, see the [Ingress User Guide](/docs/user-guide/ingress/) The '--context=federation-cluster' flag tells kubectl to submit the request to the Federation API endpoint, with the appropriate credentials. If you have not yet configured such a context, visit the [federation admin guide](/docs/admin/federation/) or one of the [administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation) -to find out how to do so. TODO: Update links +to find out how to do so. As described above, the Federated Ingress will automatically create and maintain matching Kubernetes ingresses in all of the clusters @@ -147,17 +147,28 @@ Events: 2m 2m 1 {loadbalancer-controller } Normal CREATE ip: 130.211.5.194 ``` -Note the address of your Federated Ingress +Note that: + +1. the address of your Federated Ingress corresponds with the address of all of the underlying Kubernetes ingresses (once these have been allocated - this may take up to a few minutes). - -Note also that we have not yet provisioned any backend Pods to receive +2. we have not yet provisioned any backend Pods to receive the network traffic directed to this ingress (i.e. 'Service Endpoints' behind the service backing the Ingress), so the Federated Ingress does not yet consider these to be healthy shards and will not direct traffic to any of these clusters. +3. the federation control system will +automatically reconfigure the load balancer controllers in all of the +clusters in your federation to make them consistent, and allow +them to share global load balancers. But this reconfiguration can +only complete successfully if there are no pre-existing Ingresses in +those clusters (this is a safety feature to prevent accidental +breakage of existing ingresses). So to ensure that your federated +ingresses function correctly, either start with new, empty clusters, or make +sure that you delete (and recreate if necessary) all pre-existing +Ingresses in the clusters comprising your federation. -## Adding backend services and pods +#Adding backend services and pods To render the underlying ingress shards healthy, we need to add backend Pods behind the service upon which the Ingress is based. There are several ways to achieve this, but @@ -175,6 +186,16 @@ kubectl --context=federation-cluster create -f services/nginx.yaml kubectl --context=federation-cluster create -f myreplicaset.yaml ``` +Note that in order for your federated ingress to work correctly on +Google Cloud, the node ports of all of the underlying cluster-local +services need to be identical. If you're using a federated service +this is easy to do. Simply pick a node port that is not already +being used in any of your clusters, and add that to the spec of your +federated service. If you do not specify a node port for your +federated service, each cluster will choose it's own node port for +its cluster-local shard of the service, and these will probably end +up being different, which is not what you want. + You can verify this by checking in each of the underlying clusters, for example: ``` shell @@ -258,6 +279,35 @@ Check that: `service-controller` or `replicaset-controller`, errors in the output of `kubectl logs federation-controller-manager --namespace federation`). +#### I can create a federated ingress successfully, but request load is not correctly distributed across the underlying clusters + +Check that: + +1. the services underlying your federated ingress in each cluster have + identical node ports. See [above](#creating_a_federated_ingress) for further explanation. +2. the load balancer controllers in each of your clusters are of the + correct type ("GLBC") and have been correctly reconfigured by the + federation control plane to share a global GCE load balancer (this + should happen automatically). If they of the correct type, and + have been correctly reconfigured, the UID data item in the GLBC + configmap in each cluster will be identical across all clusters. + See + [the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) + for further details. + If this is not the case, check the logs of your federation + controller manager to determine why this automated reconfiguration + might be failing. +3. no ingresses have been manually created in any of your clusters before the above + reconfiguration of the load balancer controller completed + successfully. Ingresses created before the reconfiguration of + your GLBC will interfere with the behavior of your federated + ingresses created after the reconfiguration (see + [the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid) + for further information. To remedy this, + delete any ingresses created before the cluster joined the + federation (and had it's GLBC reconfigured), and recreate them if + necessary. + #### This troubleshooting guide did not help me solve my problem Please use one of our [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance. diff --git a/docs/user-guide/images.md b/docs/user-guide/images.md index e739bb0ca9..582961593f 100644 --- a/docs/user-guide/images.md +++ b/docs/user-guide/images.md @@ -5,7 +5,7 @@ assignees: --- -Each container in a pod has its own image. Currently, the only type of image supported is a [Docker Image](https://docs.docker.com/userguide/dockerimages/). +Each container in a pod has its own image. Currently, the only type of image supported is a [Docker Image](https://docs.docker.com/engine/tutorials/dockerimages/). You create your Docker image and push it to a registry before referring to it in a Kubernetes pod. diff --git a/docs/user-guide/ingress.md b/docs/user-guide/ingress.md index 6ce1eb915d..a8324bea24 100644 --- a/docs/user-guide/ingress.md +++ b/docs/user-guide/ingress.md @@ -53,18 +53,18 @@ Make sure you review the [beta limitations](https://github.com/kubernetes/contri A minimal Ingress might look like: ```yaml -01. apiVersion: extensions/v1beta1 -02. kind: Ingress -03. metadata: -04. name: test-ingress -05. spec: -06. rules: -07. - http: -08. paths: -09. - path: /testpath -10. backend: -11. serviceName: test -12. servicePort: 80 +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: test-ingress +spec: + rules: + - http: + paths: + - path: /testpath + backend: + serviceName: test + servicePort: 80 ``` *POSTing this to the API server will have no effect if you have not configured an [Ingress controller](#ingress-controllers).* diff --git a/docs/user-guide/jobs.md b/docs/user-guide/jobs.md index ffaa6f52e1..0d897cbbc9 100644 --- a/docs/user-guide/jobs.md +++ b/docs/user-guide/jobs.md @@ -380,6 +380,6 @@ driver, and then cleans up. An advantage of this approach is that the overall process gets the completion guarantee of a Job object, but complete control over what pods are created and how work is assigned to them. -## Scheduled Jobs +## Cron Jobs -Support for creating Jobs at specified times/dates (i.e. cron) is available in Kubernetes [1.4](https://github.com/kubernetes/kubernetes/pull/11980). More information is available in the [scheduled job documents](http://kubernetes.io/docs/user-guide/scheduled-jobs/) +Support for creating Jobs at specified times/dates (i.e. cron) is available in Kubernetes [1.4](https://github.com/kubernetes/kubernetes/pull/11980). More information is available in the [cron job documents](http://kubernetes.io/docs/user-guide/cron-jobs/) diff --git a/docs/user-guide/kubectl-cheatsheet.md b/docs/user-guide/kubectl-cheatsheet.md index 14e6850f37..b207542e85 100644 --- a/docs/user-guide/kubectl-cheatsheet.md +++ b/docs/user-guide/kubectl-cheatsheet.md @@ -141,7 +141,7 @@ $ kubectl rolling-update frontend-v1 frontend-v2 --rollback # Abort exist $ cat pod.json | kubectl replace -f - # Replace a pod based on the JSON passed into stdin # Force replace, delete and then re-create the resource. Will cause a service outage. -$ kubectl replace --force -f ./pod.json +$ kubectl replace --force -f ./pod.json # Create a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000 $ kubectl expose rc nginx --port=80 --target-port=8000 @@ -251,7 +251,7 @@ Resource type | Abbreviated alias `replicasets` |`rs` `replicationcontrollers` |`rc` `resourcequotas` |`quota` -`scheduledjob` | +`cronjob` | `secrets` | `serviceaccount` |`sa` `services` |`svc` diff --git a/docs/user-guide/kubectl-conventions.md b/docs/user-guide/kubectl-conventions.md index e0f9d966a8..ad2522f663 100644 --- a/docs/user-guide/kubectl-conventions.md +++ b/docs/user-guide/kubectl-conventions.md @@ -40,7 +40,7 @@ In order for `kubectl run` to satisfy infrastructure as code: version 1.5 of kuberentes this generator is deprecated, with a plan to be removed in 1.6. Please use `job/v1` instead. * Job - use `job/v1`. -* ScheduledJob - use `scheduledjob/v2alpha1`. +* CronJob - use `cronjob/v2alpha1`. Additionally, if you didn't specify a generator flag, other flags will suggest using a specific generator. Below table shows which flags force using specific generators, @@ -52,7 +52,7 @@ depending on your cluster version: | Replication Controller | `--generator=run/v1` | `--generator=run/v1` | `--generator=run/v1` | `--restart=Always` | | Deployment | `--restart=Always` | `--restart=Always` | `--restart=Always` | N/A | | Job | `--restart=OnFailure` | `--restart=OnFailure` | `--restart=OnFailure` OR `--restart=Never` | N/A | -| Scheduled Job | `--schedule=` | N/A | N/A | N/A | +| Cron Job | `--schedule=` | N/A | N/A | N/A | Note that these flags will use a default generator only when you have not specified any flag. This also means that combining `--generator` with other flags won't diff --git a/docs/user-guide/kubectl/kubectl_run.md b/docs/user-guide/kubectl/kubectl_run.md index c0a7d9cc6d..9b3dfb409e 100644 --- a/docs/user-guide/kubectl/kubectl_run.md +++ b/docs/user-guide/kubectl/kubectl_run.md @@ -50,7 +50,7 @@ kubectl run nginx --image=nginx --command -- ... # Start the perl container to compute π to 2000 places and print it out. kubectl run pi --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)' -# Start the scheduled job to compute π to 2000 places and print it out every 5 minutes. +# Start the cron job to compute π to 2000 places and print it out every 5 minutes. kubectl run pi --schedule="0/5 * * * ?" --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)' ``` diff --git a/docs/user-guide/node-selection/index.md b/docs/user-guide/node-selection/index.md index 49d30b51c9..725848b544 100644 --- a/docs/user-guide/node-selection/index.md +++ b/docs/user-guide/node-selection/index.md @@ -173,7 +173,7 @@ on node N if node N has a label with key `failure-domain.beta.kubernetes.io/zone such that there is at least one node in the cluster with key `failure-domain.beta.kubernetes.io/zone` and value V that is running a pod that has a label with key "security" and value "S1".) The pod anti-affinity rule says that the pod cannot schedule onto a node if that node is already running a pod with label -having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kuberntes.io/zone` then +having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kubernetes.io/zone` then it would mean that the pod cannot schedule onto a node if that node is in the same zone as a pod with label having key "security" and value "S2".) See the [design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/podaffinity.md). for many more examples of pod affinity and anti-affinity, both the `requiredDuringSchedulingIgnoredDuringExecution` diff --git a/docs/user-guide/persistent-volumes/volumes/local-01.yaml b/docs/user-guide/persistent-volumes/volumes/local-01.yaml index 25acecca93..a465c65149 100644 --- a/docs/user-guide/persistent-volumes/volumes/local-01.yaml +++ b/docs/user-guide/persistent-volumes/volumes/local-01.yaml @@ -10,4 +10,4 @@ spec: accessModes: - ReadWriteOnce hostPath: - path: "/somepath/data01" + path: "/tmp/data01" diff --git a/docs/user-guide/persistent-volumes/walkthrough.md b/docs/user-guide/persistent-volumes/walkthrough.md index 30b24feac2..c82a37f7d0 100644 --- a/docs/user-guide/persistent-volumes/walkthrough.md +++ b/docs/user-guide/persistent-volumes/walkthrough.md @@ -27,7 +27,7 @@ for ease of development and testing. You'll create a local `HostPath` for this support local storage on the host at this time. There is no guarantee your pod ends up on the correct node where the `HostPath` resides. ```shell -# This will be nginx's webroot +# This will be nginx's webroot; execute this on the node where your pod will run. $ mkdir /tmp/data01 $ echo 'I love Kubernetes storage!' > /tmp/data01/index.html ``` @@ -125,4 +125,4 @@ I love Kubernetes storage! Hopefully this simple guide is enough to get you started with PersistentVolumes. If you have any questions, join the team on [Slack](/docs/troubleshooting/#slack) and ask! -Enjoy! \ No newline at end of file +Enjoy! diff --git a/docs/user-guide/petset/bootstrapping/index.md b/docs/user-guide/petset/bootstrapping/index.md index 03ba721edc..9dc4f7e899 100644 --- a/docs/user-guide/petset/bootstrapping/index.md +++ b/docs/user-guide/petset/bootstrapping/index.md @@ -88,7 +88,7 @@ vm-1 # printf "GET / HTTP/1.0\r\n\r\n" | netcat vm-0.ub 80 It's worth exploring what just happened. Init containers run sequentially *before* the application container. In this example we used the init container to copy shared libraries from the rootfs, while preserving user installed packages across container restart. ```yaml -pod.alpha.kubernetes.io/init-containers: '[ +pod.beta.kubernetes.io/init-containers: '[ { "name": "rootfs", "image": "ubuntu:15.10", diff --git a/docs/user-guide/petset/bootstrapping/petset_peers.yaml b/docs/user-guide/petset/bootstrapping/petset_peers.yaml index f8393b5c2c..4f992ead71 100644 --- a/docs/user-guide/petset/bootstrapping/petset_peers.yaml +++ b/docs/user-guide/petset/bootstrapping/petset_peers.yaml @@ -29,7 +29,7 @@ spec: app: nginx annotations: pod.alpha.kubernetes.io/initialized: "true" - pod.alpha.kubernetes.io/init-containers: '[ + pod.beta.kubernetes.io/init-containers: '[ { "name": "peerfinder", "image": "gcr.io/google_containers/peer-finder:0.1", diff --git a/docs/user-guide/petset/bootstrapping/petset_vm.yaml b/docs/user-guide/petset/bootstrapping/petset_vm.yaml index c506a1bac6..a3da5211a3 100644 --- a/docs/user-guide/petset/bootstrapping/petset_vm.yaml +++ b/docs/user-guide/petset/bootstrapping/petset_vm.yaml @@ -27,7 +27,7 @@ spec: app: ub annotations: pod.alpha.kubernetes.io/initialized: "true" - pod.alpha.kubernetes.io/init-containers: '[ + pod.beta.kubernetes.io/init-containers: '[ { "name": "rootfs", "image": "ubuntu:15.10", diff --git a/docs/user-guide/pod-states.md b/docs/user-guide/pod-states.md index b29270e5f8..8f745e9f56 100644 --- a/docs/user-guide/pod-states.md +++ b/docs/user-guide/pod-states.md @@ -66,8 +66,8 @@ The possible values for RestartPolicy are `Always`, `OnFailure`, or `Never`. If Three types of controllers are currently available: - Use a [`Job`](/docs/user-guide/jobs/) for pods which are expected to terminate (e.g. batch computations). -- Use a [`ReplicationController`](/docs/user-guide/replication-controller/) for pods which are not expected to - terminate (e.g. web servers). +- Use a [`ReplicationController`](/docs/user-guide/replication-controller/) or [`Deployment`](/docs/user-guide/deployments/) + for pods which are not expected to terminate (e.g. web servers). - Use a [`DaemonSet`](/docs/admin/daemons/): Use for pods which need to run 1 per machine because they provide a machine-specific system service. If you are unsure whether to use ReplicationController or Daemon, then see [Daemon Set versus diff --git a/docs/user-guide/pods/init-container.md b/docs/user-guide/pods/init-container.md new file mode 100644 index 0000000000..75b6efcac3 --- /dev/null +++ b/docs/user-guide/pods/init-container.md @@ -0,0 +1,169 @@ +--- +assignees: +- erictune + +--- + +* TOC +{:toc} + +In addition to having one or more main containers (or **app containers**), a +pod can also have one or more **init containers** which run before the app +containers. Init containers allow you to reduce and reorganize setup scripts +and "glue code". + +## Overview + +An init container is exactly like a regular container, except that it always +runs to completion and each init container must complete successfully before +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 +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) + +Once the feature exits beta, the init containers will be specified on the Pod +Spec alongside the app `containers` array. +The status of the init containers is returned as another annotation - +`pod.beta.kubernetes.io/init-container-statuses` -- as an array of the +container statuses (similar to the `status.containerStatuses` field). + +Init containers support all of the same features as normal containers, +including resource limits, volumes, and security settings. The resource +requests and limits for an init container are [handled slightly differently]( +#resources). Init containers do not support readiness probes since they will +run to completion before the pod can be ready. +An init container has all of the fields of an app container. + +If you specify multiple init containers for a pod, those containers run one at +a time in sequential order. Each must succeed before the next can run. Once all +init containers have run to completion, Kubernetes initializes the pod and runs +the application containers as usual. + +## What are Init Containers Good For? + +Because init containers have separate images from application containers, they +have some advantages for start-up related code. These include: + +* they can contain utilities that are not desirable to include in the app container + image for security reasons, +* they can contain utilities or custom code for setup that is not present in an app + image. (No need to make an image `FROM` another image just to use a tool like + `sed`, `awk`, `python`, `dig`, etc during setup). +* the application image builder and the deployer roles can work independently without + the need to jointly build a single app image. + +Because init containers have different filesystem view (Linux namespaces) from +app containers, they can be given access to Secrets that the app containers are +not able to access. + +Since init containers run to completion before any app containers start, and +since app containers run in parallel, they provide an easier way to block or +delay the startup of application containers until some precondition is met. + +Because init containers run in sequence and there can be multiple init containers, +they can be composed easily. + +Here are some ideas for how to use init containers: +- Wait for a service to be created with a shell command like: + `for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; exit 1` +- Register this pod with a remote server with a command like: + `curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d 'instance=$(POD_NAME)&ip=$(POD_IP)'` + using `POD_NAME` and `POD_IP` from the downward API. +- Wait for some time before starting the app container with a command like `sleep 60`. +- Clone a git repository into a volume +- Place values like a POD_IP into a configuration file, and run a template tool (e.g. jinja) + to generate a configuration file to be consumed by the main app contianer. +``` + +Complete usage examples can be found in the [PetSets +guide](docs/user-guide/petset/bootstrapping/index.md) and the [Production Pods +guide](/docs/user-guide/production-pods.md#handling-initialization). + + +## Detailed Behavior + +Each pod may have 0..N init containers defined along with the existing +1..M app containers. + +On startup of the pod, after the network and volumes are initialized, the init +containers are started in order. Each container must exit successfully before +the next is invoked. If a container fails to start (due to the runtime) or +exits with failure, it is retried according to the pod RestartPolicy, except +when the pod restart policy is RestartPolicyAlways, in which case just the init +containers use RestartPolicyOnFailure. + +A pod cannot be ready until all init containers have succeeded. The ports on an +init container are not aggregated under a service. A pod that is being +initialized is in the `Pending` phase but should has a condition `Initializing` +set to `true`. + +If the pod is [restarted](#pod-restart-reasons) all init containers must +execute again. + +Changes to the init container spec are limited to the container image field. +Altering a init container image field is equivalent to restarting the pod. + +Because init containers can be restarted, retried, or reexecuted, init container +code should be idempotent. In particular, code that writes to files on EmptyDirs +should be prepared for the possibility that an output file already exists. + +An init container has all of the fields of an app container. The following +fields are prohibited from being used on init containers by validation: + +* `readinessProbe` - init containers must exit for pod startup to continue, + are not included in rotation, and so cannot define readiness distinct from + completion. + +Init container authors may use `activeDeadlineSeconds` on the pod and +`livenessProbe` on the container to prevent init containers from failing +forever. The active deadline includes init containers. + +The name of each app and init container in a pod must be unique - it is a +validation error for any container to share a name. + +### Resources + +Given the ordering and execution for init containers, the following rules +for resource usage apply: + +* The highest of any particular resource request or limit defined on all init + containers is the **effective init request/limit** +* The pod's **effective request/limit** for a resource is the higher of: + * sum of all app containers request/limit for a resource + * effective init request/limit for a resource +* Scheduling is done based on effective requests/limits, which means + init containers can reserve resources for initialization that are not used + during the life of the pod. +* QoS tier of the pod's **effective QoS tier** is the QoS tier for init containers + and app containers alike. + +Quota and limits are applied based on the effective pod request and +limit. + +Pod level cGroups are based on the effective pod request and limit, the +same as the scheduler. + + +## Pod Restart Reasons + +A Pod may "restart", causing reexecution of init containers, for the following +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 + * 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. + +## Support and compatibilty + +A cluster with Kubelet and Apiserver version 1.4.0 or greater supports init +containers with the beta annotations. Support varies for other combinations of +Kubelet and Apiserver version; see the [release notes +](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md) for details. + + diff --git a/docs/user-guide/production-pods.md b/docs/user-guide/production-pods.md index 440ac4619a..bf85fdaf8f 100644 --- a/docs/user-guide/production-pods.md +++ b/docs/user-guide/production-pods.md @@ -204,6 +204,8 @@ The status of the init containers is returned as another annotation - `pod.beta. Init containers support all of the same features as normal containers, including resource limits, volumes, and security settings. The resource requests and limits for an init container are handled slightly different than normal containers since init containers are run one at a time instead of all at once - any limits or quotas will be applied based on the largest init container resource quantity, rather than as the sum of quantities. Init containers do not support readiness probes since they will run to completion before the pod can be ready. +[Complete Init Container Documentation](/docs/user-guide/pods/init-containers.md) + ## Lifecycle hooks and termination notice @@ -218,7 +220,7 @@ The specification of a pre-stop hook is similar to that of probes, but without t ## Termination message -In order to achieve a reasonably high level of availability, especially for actively developed applications, it's important to debug failures quickly. Kubernetes can speed debugging by surfacing causes of fatal errors in a way that can be display using [`kubectl`](/docs/user-guide/kubectl/kubectl) or the [UI](/docs/user-guide/ui), in addition to general [log collection](/docs/user-guide/logging). It is possible to specify a `terminationMessagePath` where a container will write its 'death rattle'?, such as assertion failure messages, stack traces, exceptions, and so on. The default path is `/dev/termination-log`. +In order to achieve a reasonably high level of availability, especially for actively developed applications, it's important to debug failures quickly. Kubernetes can speed debugging by surfacing causes of fatal errors in a way that can be display using [`kubectl`](/docs/user-guide/kubectl/) or the [UI](/docs/user-guide/ui), in addition to general [log collection](/docs/user-guide/logging). It is possible to specify a `terminationMessagePath` where a container will write its 'death rattle'?, such as assertion failure messages, stack traces, exceptions, and so on. The default path is `/dev/termination-log`. Here is a toy example: diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index f97c6185b8..c55868f1f1 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -265,7 +265,7 @@ All listed keys must exist in the corresponding secret. Otherwise, the volume is **Secret files permissions** You can also specify the permission mode bits files part of a secret will have. -If you don't specify any, `0644` is used by default. You can sepecify a default +If you don't specify any, `0644` is used by default. You can specify a default mode for the whole secret volume and override per key if needed. For example, you can specify a default mode like this: diff --git a/docs/user-guide/service-accounts.md b/docs/user-guide/service-accounts.md index 3fa9252034..1df4635da9 100644 --- a/docs/user-guide/service-accounts.md +++ b/docs/user-guide/service-accounts.md @@ -31,8 +31,8 @@ you get the raw json or yaml for a pod you have created (e.g. `kubectl get pods/podname -o yaml`), you can see the `spec.serviceAccount` field has been [automatically set](/docs/user-guide/working-with-resources/#resources-are-automatically-modified). -You can access the API using a proxy or with a client library, as described in -[Accessing the Cluster](/docs/user-guide/accessing-the-cluster/#accessing-the-api-from-a-pod). +With service accounts, you can access the API inside the pod using a proxy or with a client library, +as described in [Accessing the Cluster](/docs/user-guide/accessing-the-cluster/#accessing-the-api-from-a-pod). ## Using Multiple Service Accounts. diff --git a/docs/user-guide/services/index.md b/docs/user-guide/services/index.md index 94faabcd1c..e9b0660d39 100644 --- a/docs/user-guide/services/index.md +++ b/docs/user-guide/services/index.md @@ -182,7 +182,7 @@ In Kubernetes v1.0 the proxy was purely in userspace. In Kubernetes v1.1 an iptables proxy was added, but was not the default operating mode. Since Kubernetes v1.2, the iptables proxy is the default. -As of Kubernetes v1.0, `Services` are a "layer 3" (TCP/UDP over IP) construct. +As of Kubernetes v1.0, `Services` are a "layer 4" (TCP/UDP over IP) construct. In Kubernetes v1.1 the `Ingress` API was added (beta) to represent "layer 7" (HTTP) services. @@ -345,7 +345,7 @@ can do a DNS SRV query for `"_http._tcp.my-service.my-ns"` to discover the port number for `"http"`. The Kubernetes DNS server is the only way to access services of type -`ExternalName`. +`ExternalName`. More information is available in the [DNS Admin Guide](http://kubernetes.io/docs/admin/dns/). ## Headless services diff --git a/docs/user-guide/sharing-clusters.md b/docs/user-guide/sharing-clusters.md index 34a53d670e..723f54fa14 100644 --- a/docs/user-guide/sharing-clusters.md +++ b/docs/user-guide/sharing-clusters.md @@ -115,12 +115,12 @@ make all four clusters available on both hosts by running # on host2, copy host1's default kubeconfig, and merge it from env $ scp host1:/path/to/home1/.kube/config /path/to/other/.kube/config -$ export $KUBECONFIG=/path/to/other/.kube/config +$ export KUBECONFIG=/path/to/other/.kube/config # on host1, copy host2's default kubeconfig and merge it from env $ scp host2:/path/to/home2/.kube/config /path/to/other/.kube/config -$ export $KUBECONFIG=/path/to/other/.kube/config +$ export KUBECONFIG=/path/to/other/.kube/config ``` Detailed examples and explanation of `kubeconfig` loading/merging rules can be found in [kubeconfig-file](/docs/user-guide/kubeconfig-file). diff --git a/docs/user-guide/thirdpartyresources.md b/docs/user-guide/thirdpartyresources.md index d8f2bc5ba9..a1035d44c4 100644 --- a/docs/user-guide/thirdpartyresources.md +++ b/docs/user-guide/thirdpartyresources.md @@ -22,7 +22,7 @@ Each `ThirdPartyResource` has the following: * `description` - A free text description of the resource. * `versions` - A list of the versions of the resource. -The `kind` for a `ThirdPartyResource` takes the form `.`. You are expected to provide a unique kind and domain name in order to avoid conflicts with other `ThirdPartyResource` objects. Kind names will be converted to CamelCase when creating instances of the `ThirdPartyResource`. Hypens in the `kind` are assumed to be word breaks. For instance the kind `camel-case` would be converted to `CamelCase` but `camelcase` would be converted to `Camelcase`. +The `kind` for a `ThirdPartyResource` takes the form `.`. You are expected to provide a unique kind and domain name in order to avoid conflicts with other `ThirdPartyResource` objects. Kind names will be converted to CamelCase when creating instances of the `ThirdPartyResource`. Hyphens in the `kind` are assumed to be word breaks. For instance the kind `camel-case` would be converted to `CamelCase` but `camelcase` would be converted to `Camelcase`. Other fields on the `ThirdPartyResource` are treated as custom data fields. These fields can hold arbitrary JSON data and have any structure. diff --git a/docs/user-guide/working-with-resources.md b/docs/user-guide/working-with-resources.md index 5b300ee6bd..d2aeeb621e 100644 --- a/docs/user-guide/working-with-resources.md +++ b/docs/user-guide/working-with-resources.md @@ -46,7 +46,7 @@ The system adds fields in several ways: - Some fields are added synchronously with creation of the resource and some are set asynchronously. - For example: `metadata.uid` is set synchronously. (Read more about [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata)). - - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read mode about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization) ). + - For example, `status.hostIP` is set only after the pod has been scheduled. This often happens fast, but you may notice pods which do not have this set yet. This is called Late Initialization. (Read more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization)). - Some fields are set to default values. Some defaults vary by cluster and some are fixed for the API at a certain version. (Read more about [defaulting](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#defaulting)). - For example, `spec.containers[0].imagePullPolicy` always defaults to `IfNotPresent` in api v1. - For example, `spec.containers[0].resources.limits.cpu` may be defaulted to `100m` on some clusters, to some other value on others, and not defaulted at all on others. diff --git a/images/square-logos/datadog.png b/images/square-logos/datadog.png index 82d6d11aaf..aeab0f227f 100644 Binary files a/images/square-logos/datadog.png and b/images/square-logos/datadog.png differ diff --git a/images/square-logos/endocode.png b/images/square-logos/endocode.png new file mode 100644 index 0000000000..a90189d6f9 Binary files /dev/null and b/images/square-logos/endocode.png differ diff --git a/images/square-logos/giant_swarm.png b/images/square-logos/giant_swarm.png new file mode 100644 index 0000000000..6434f98735 Binary files /dev/null and b/images/square-logos/giant_swarm.png differ diff --git a/images/square-logos/mirantis.png b/images/square-logos/mirantis.png new file mode 100644 index 0000000000..9dc83103d9 Binary files /dev/null and b/images/square-logos/mirantis.png differ diff --git a/images/square-logos/stackpoint.png b/images/square-logos/stackpoint.png new file mode 100644 index 0000000000..dd2822d493 Binary files /dev/null and b/images/square-logos/stackpoint.png differ diff --git a/test/examples_test.go b/test/examples_test.go index 7e5660c4f9..63fea3c5bc 100644 --- a/test/examples_test.go +++ b/test/examples_test.go @@ -242,7 +242,7 @@ func TestExampleObjectSchemas(t *testing.T) { "redis-resource-deployment": &extensions.Deployment{}, "redis-secret-deployment": &extensions.Deployment{}, "run-my-nginx": &extensions.Deployment{}, - "sj": &batch.CronJob{}, + "cronjob": &batch.CronJob{}, }, "../docs/admin": { "daemon": &extensions.DaemonSet{},