├── AUTHORS ├── CONTRIBUTING.md ├── CONTRIBUTORS ├── LICENSE ├── README.md └── kubehost /AUTHORS: -------------------------------------------------------------------------------- 1 | # This is the official list of the Kubehost authors for copyright purposes. 2 | # This file is distinct from the CONTRIBUTORS files. 3 | # See the latter for an explanation. 4 | # Names should be added to this file as: 5 | # Name or Organization 6 | # The email address is not required for organizations. 7 | 8 | Google LLC 9 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to Contribute 2 | 3 | We'd love to accept your patches and contributions to this project. There are 4 | just a few small guidelines you need to follow. 5 | 6 | ## Contributor License Agreement 7 | 8 | Contributions to this project must be accompanied by a Contributor License 9 | Agreement. You (or your employer) retain the copyright to your contribution; 10 | this simply gives us permission to use and redistribute your contributions as 11 | part of the project. Head over to to see 12 | your current agreements on file or to sign a new one. 13 | 14 | You generally only need to submit a CLA once, so if you've already submitted one 15 | (even if it was for a different project), you probably don't need to do it 16 | again. 17 | 18 | ## Code reviews 19 | 20 | All submissions, including submissions by project members, require review. We 21 | use GitHub pull requests for this purpose. Consult 22 | [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23 | information on using pull requests. 24 | 25 | ## Community Guidelines 26 | 27 | This project follows [Google's Open Source Community 28 | Guidelines](https://opensource.google.com/conduct/). 29 | -------------------------------------------------------------------------------- /CONTRIBUTORS: -------------------------------------------------------------------------------- 1 | # People who have agreed to one of the CLAs and can contribute patches. 2 | # The AUTHORS file lists the copyright holders; this file 3 | # lists people. For example, Google employees are listed here 4 | # but not in AUTHORS, because Google holds the copyright. 5 | # 6 | # https://developers.google.com/open-source/cla/individual 7 | # https://developers.google.com/open-source/cla/corporate 8 | # 9 | # Names should be added to this file as: 10 | # Name 11 | 12 | William Denniss 13 | Van Tu 14 | Cong Liu 15 | 16 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # kubehost 2 | 3 | Kubehost helps you expose services directly on nodes of your 4 | Google Kubernetes Engine (GKE) cluster. 5 | 6 | The common way to expose a service and get an external IP is 7 | `kubectl expose --type=LoadBalancer"`, which will expose 8 | your deployment on a production-grade Google Cloud Load Balancer. 9 | Sometimes you just want to expose a service on your VM directly, like 10 | during development where uptime and reliability are not as important. 11 | That's where Kubehost comes in. 12 | 13 | Kubehost uses existing features of GKE to expose your service directly 14 | onto one of the VMs in your cluster, by creating a Pod that runs on 15 | the VM's network and forwards traffic to your in-cluster (ClusterIP) 16 | service, and creating firewall rules to permit external traffic. 17 | While you could do this manually, Kubehost takes the toil out of 18 | managing this configuration by automating the necessary actions. 19 | 20 |
21 | 22 | > ### :warning: For development use only 23 | > kubehost is NOT designed for production use! Nodes in GKE 24 | > are designed to be redundant, meaning they can fail. 25 | > When the node on which your service is exposed via kubehost fails or 26 | > is upgraded, your service will experience several minutes of downtime. 27 | > By comparison, if you use a production-grade Google Cloud Load 28 | > Balancer (and you have enough replicas of your Pod spread over 29 | > multiple nodes with properly implemented health and readiness checks) 30 | > then a node can fail with only minimal impact to the availability of 31 | > your service. At any time you can upgrade to a Google Cloud Load 32 | > Balancer with the `kubehost upgrade` command. 33 | 34 | ## Installation 35 | 36 | `kubehost` is a bash script. To install, clone this repository and add 37 | it to your `$PATH`, or copy `kubehost` to your `/usr/local/bin/`. 38 | 39 | You may need to set the executable permission, i.e. `chmod +x kubehost`. 40 | 41 | ## Configuration 42 | 43 | Before using `kubehost`, you need to ensure both `gcloud` and `kubectl` 44 | are configured with your desired project & cluster. 45 | 46 | 1. run `gcloud init` to select your account, project and region 47 | containing the GKE cluster. 48 | 2. run 49 | [get-credentials](https://cloud.google.com/sdk/gcloud/reference/container/clusters/get-credentials) 50 | to configure `kubectl`. 51 | 52 | ## Exposing a Deployment with kubehost 53 | 54 | 1. Create your deployment like normal. 55 | 2. Create a ClusterIP service for your deployment (this is the default 56 | service type, so no need to specify any type), **on your desired 57 | external port**. 58 | 3. Run `kubehost bind ${SERVICE}`, where `${SERVICE}` is the name of 59 | the Kubernetes service you created at step 2. 60 | 61 | What this does is create some "glue" in the form of a hostPort 62 | deployment so that your service is bound to port you specified in the 63 | service on your node's external IP (read "under the hood" for a longer 64 | technical description). It also opens the necessary GCP firewall rules. 65 | 66 | To undo, `kubehost unbind ${SERVICE}` 67 | 68 | Complete example: 69 | 70 | ```bash 71 | kubectl run hello --image gcr.io/google-samples/hello-app:1.0 --port 8080 72 | kubectl expose deployment hello --port 80 --target-port 8080 --name hello-service 73 | kubehost bind hello-service 74 | ``` 75 | 76 | Cleanup: 77 | ```bash 78 | kubehost unbind hello-service 79 | kubectl delete deployment hello 80 | kubectl delete service hello-service 81 | ``` 82 | 83 | ## Switching between hostPort and a Load Balancer 84 | 85 | ### Upgrading to a Load Balancer from hostPort 86 | 87 | Is your app ready for prime time? Remove the hostPort Pod "glue", and 88 | convert your Service into one backed by a 89 | [Google Cloud Load Balancer](https://cloud.google.com/load-balancing/) 90 | with one simple command: 91 | 92 | ```bash 93 | kubehost upgrade ${SERVICE} 94 | ``` 95 | 96 | Where `${SERVICE}` is the name of your Cluster IP service. 97 | 98 | ### Downgrading a Load Balancer to hostPort 99 | 100 | Did you already expose your service with a Load Balancer and found it's 101 | more than you needed? Convert it to an internal ClusterIP service, 102 | and expose it on a host in one command with: 103 | 104 | ```bash 105 | kubehost downgrade ${SERVICE} 106 | ``` 107 | 108 | Where `${SERVICE}` is the name of your Kubernetes service of type 109 | LoadBalancer. 110 | 111 | ## Limitations 112 | 113 | * Kubehost currently works with services that have a single port. If you 114 | need to expose two ports, create two ClusterIP services. 115 | * Kubehost is not designed for production usage, see the note above. 116 | * Kubehost doesn't give you a static IP. The IP address of node may 117 | change which will affect your service. You can create a static IP 118 | and use the [kubeIP](https://github.com/doitintl/kubeIP) operator to 119 | keep it assigned through node maintenance events. 120 | 121 | ## Under the Hood 122 | 123 | What Kubehost is doing when you call `bind` is creating 124 | a Kubernetes Deployment with a single replica of a Pod that uses 125 | hostPort to bind onto the host's network interface. The container in 126 | this Pod forwards traffic to your ClusterIP service. 127 | 128 | While you could instead change your deployment to use hostPort directly 129 | we think this approach is superior, as: 130 | 131 | 1. It's closer to the production Kubernetes experience where deployments 132 | have a matching service to receive traffic. 133 | 2. It's easier to switch between this and a production setup by 134 | changing the Service type to LoadBalancer, and removing the hostPort 135 | deployment (and vice-versa) – no need to modify your application 136 | deployment. 137 | 3. Your deployment's replica count isn't limited by available ports. 138 | -------------------------------------------------------------------------------- /kubehost: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # kubehost: expose services using hostPort 3 | 4 | # Copyright 2018 Google LLC 5 | # 6 | # Licensed under the Apache License, Version 2.0 (the "License"); 7 | # you may not use this file except in compliance with the License. 8 | # You may obtain a copy of the License at 9 | # 10 | # http://www.apache.org/licenses/LICENSE-2.0 11 | # 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | 18 | [[ -n "${DEBUG}" ]] && set -x 19 | 20 | #set -o pipefail -o noclobber -o nounset #-o errexit 21 | 22 | # Trap exit 67 and cascade 23 | set -E 24 | trap '[ "$?" -ne 67 ] || exit 67' ERR 25 | 26 | usage() { 27 | cat <<"EOF" 28 | Usage: 29 | bind : Create a hostPort deployment and corresponding 30 | firewall rule for a service. 31 | unbind : Delete the hostPort deployment and firewall rule 32 | created with 'bind' for a service. 33 | getip : Show the IP of a service created with 'bind'. 34 | create-firewall : Create a GCP firewall rule for the hostPort 35 | deployment created with 'bind'. 36 | delete-firewall : Delete a GCP firewall rule for the hostPort 37 | deployment created with 'bind'. 38 | upgrade : Convert a service that had a hostPort deployment 39 | exposed with 'bind' to a production loadBalancer 40 | service. 41 | downgrade : Convert a loadBalancer service into a hostPort 42 | deployment. 43 | demo : Create and bind an example deployment. 44 | demo_cleanup : Delete an example deployment. 45 | version : Display version information. 46 | -h,--help : Show this message. 47 | Options: 48 | --skip-firewall, -s : For 'bind' and 'unbind', doesn't modify firewall 49 | rules. 50 | --firewall-node-only : By default, firewall rules are applied to all 51 | nodes on the cluster due to the fact that the 52 | deployment may move around. This flag will create 53 | a specific firewall rule for the node only. 54 | EOF 55 | exit 1 56 | } 57 | 58 | # Logs to stderr. 59 | # @param {string*} Text to echo to stderr 60 | echoerr() { echo "$@" 1>&2; } 61 | 62 | # Validates if the Kubernetes service exists. 63 | # @param {string} name of the Kubernetes service 64 | # @return 67 if the service doesn't exist 65 | validate_service_exists() { 66 | declare -r service=$1 67 | kubectl get service ${service} 68 | if [ $? -ne 0 ]; then 69 | exit 67 70 | fi 71 | } 72 | 73 | # Validates that the given Kubernetes service can be used with hostPort. 74 | # @param {string} name of the Kubernetes service to test 75 | # @return 67 if invalid, otherwise 0 76 | validate_service_for_bind() { 77 | declare -r service=$1 78 | validate_service_exists "${service}" 79 | declare -r service_type="$(kubectl get service ${service} -o=jsonpath='{.spec.type}')" 80 | 81 | if [[ "${service_type}" == "LoadBalancer" ]]; then 82 | echoerr "Service '${service}' is of type LoadBalancer, you don't need" \ 83 | "to bind it to the host." 84 | exit 67 85 | fi 86 | 87 | if [[ "${service_type}" == "NodePort" ]]; then 88 | echoerr "Service '${service}' is of type NodePort which is not" \ 89 | "supported." 90 | echoerr "Use ClusterIP with the port you wish to expose, as kubehost" \ 91 | "will expose that same port via a hostPort deployment." 92 | exit 67 93 | fi 94 | } 95 | 96 | # Validates that the given Kubernetes service can be upgraded to type 97 | # LoadBalancer. 98 | # @param {string} name of the Kubernetes service to validate 99 | # @return 67 if invalid, otherwise 0 100 | validate_service_for_upgrade() { 101 | declare -r service=$1 102 | validate_service_exists "${service}" 103 | declare -r service_type="$(kubectl get service ${service} -o=jsonpath='{.spec.type}')" 104 | 105 | if [[ "${service_type}" != "ClusterIP" ]]; then 106 | echoerr "This command expects the service '${service}' to be of" \ 107 | "ClusterIP type." 108 | exit 67 109 | fi 110 | } 111 | 112 | # Validates that the given Kubernetes service can be downgraded to type 113 | # hostPort. 114 | # @param {string} name of the Kubernetes service to validate 115 | # @return 67 if invalid, otherwise 0 116 | validate_service_for_downgrade() { 117 | declare -r service=$1 118 | validate_service_exists "${service}" 119 | declare -r service_type="$(kubectl get service ${service} -o=jsonpath='{.spec.type}')" 120 | 121 | if [[ "${service_type}" != "LoadBalancer" ]]; then 122 | echoerr "This command expects the service '${service}' to be of" \ 123 | "LoadBalancer type." 124 | exit 67 125 | fi 126 | } 127 | 128 | # Generates the hostPort deployment name for a given service. 129 | # @param {string} name of the Kubernetes service 130 | # @print the generated hostport deployment name 131 | generate_deployment_name_for_service() { 132 | declare -r service=$1 133 | declare -r deployment="${service}-hostport" 134 | echo "${deployment}" 135 | } 136 | 137 | # Creates a deployment with a hostPort matching the service's port. Note only 138 | # the first port is used if the service has multiple ports. 139 | # @param {string} name of the service to expose 140 | # @print the name of the deployment that was created 141 | expose_service() { 142 | declare -r service=$1 143 | declare -r deployment="$(generate_deployment_name_for_service ${service})" 144 | declare -r service_port="$(kubectl get service ${service} -o=jsonpath='{.spec.ports[0].port}')" 145 | declare -r service_protocol="$(kubectl get service ${service} -o=jsonpath='{.spec.ports[0].protocol}')" 146 | echoerr "Creating hostPort deployment '${deployment}' for service" \ 147 | "'${service}' (${service_protocol}:${service_port})." 148 | declare -r overrides=" 149 | { 150 | \"spec\": { 151 | \"template\":{ 152 | \"spec\": { 153 | \"containers\": [{ 154 | \"name\":\"${deployment}\", 155 | \"image\":\"gcr.io/google_containers/proxy-to-service:v2\", 156 | \"args\":[ 157 | \"${service_protocol}\", 158 | \"${service_port}\", 159 | \"${service}\"], 160 | \"ports\":[{ 161 | \"protocol\": \"${service_protocol}\", 162 | \"containerPort\": "${service_port}", 163 | \"hostPort\": "${service_port}" 164 | }], 165 | \"resources\": { 166 | \"requests\": { 167 | \"cpu\": \"10m\", 168 | \"memory\": \"10Mi\" 169 | } 170 | } 171 | }] 172 | } 173 | } 174 | } 175 | }" 176 | 177 | kubectl run "${deployment}" \ 178 | --image=gcr.io/google_containers/proxy-to-service:v2 \ 179 | --overrides="${overrides}" 1>&2 180 | 181 | echo "${deployment}" 182 | } 183 | 184 | # Waits until the given deployment has at least 1 replica available. 185 | # @param {string} name of the deployment to wait for 186 | # @return 67 if waiting timed out, otherwise 0 187 | wait_deployment_available() { 188 | declare -r deployment=$1 189 | local available=-1 190 | local counter=0 191 | local -r delta=1 limit=120 192 | echoerr "Waiting for available replicas of deployment '${deployment}'" 193 | while [[ "${available}" -lt 1 ]]; do 194 | sleep "${delta}" 195 | counter="$((counter + delta))" 196 | available="$(kubectl get deployment ${deployment} -o=jsonpath='{.status.availableReplicas}')" 197 | if [ "${counter}" -gt "${limit}" ]; then 198 | echoerr "No replicas available for deployment '${deployment}'." \ 199 | "Either it's really slow to deploy, or your hostPort" \ 200 | "deployment can't be scheduled due to the lack of an" \ 201 | "available port." 202 | exit 67 203 | fi 204 | done 205 | } 206 | 207 | # Returns the external IP assigned to a service of type loadBalancer. 208 | # @param {string} name of the service 209 | # @print The external IP of the service. 210 | # @return 67 if load balancer is not ready after certain timeout 211 | get_external_ip() { 212 | declare -r service=$1 213 | local ip="" 214 | local counter=0 215 | local -r delta=1 limit=120 216 | echoerr "Waiting for load balancer to be configured for service '${service}'" 217 | while [[ "${ip}" == "" ]]; do 218 | sleep "${delta}" 219 | counter="$((counter + delta))" 220 | ip="$(kubectl get service ${service} -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')" 221 | if [ "${counter}" -gt "${limit}" ]; then 222 | echoerr "Failed to get the external IP for service '${service}'." 223 | exit 67 224 | fi 225 | done 226 | echo "${ip}" 227 | } 228 | 229 | # Gets the node on which the given deployment was deployed to. 230 | # @param {string} Name of the deployment to query 231 | # @print The node on which the deployment was deployed. 232 | # @return 67 if the deployment was not found or isn't present on any nodes 233 | get_hostport_deployment_node() { 234 | declare -r deployment=$1 235 | declare -r host_pod="$(kubectl get pods -o=jsonpath={.items[?\(@.metadata.labels.run==\"${deployment}\"\)].metadata.name})" 236 | if [[ ! "${host_pod}" ]]; then 237 | echoerr "Deployment '${deployment}' not found, exiting." 238 | exit 67 239 | fi 240 | declare -r node="$(kubectl get pod ${host_pod} -o=jsonpath={.spec.nodeName})" 241 | if [[ ! "${node}" ]]; then 242 | echoerr "Deployment '${deployment}' is not on any node." 243 | exit 67 244 | fi 245 | echo "${node}" 246 | } 247 | 248 | # Returns the IP address of the node. 249 | # @param {string} name of the deployment to query 250 | # @return 67 if waiting timed out, otherwise 0 251 | get_hostport_deployment_ip() { 252 | local -r deployment=$1 253 | local -r node="$(get_hostport_deployment_node ${deployment})" 254 | local -r ip="$(kubectl get node ${node} -o=jsonpath='{.status.addresses[?(@.type=="ExternalIP")].address}')" 255 | echo "$ip" 256 | } 257 | 258 | # Returns 0 if the node appears in the compute instances list. 259 | # A non-0 result likely indicates the user's gcloud isn't setup correctly. 260 | # @param {string} name of the node to lookup 261 | # @return 0 if the node exists, otherwise 1 262 | validate_gcloud_node() { 263 | declare -r node=$1 264 | declare -r result="$(gcloud --format='value(name)' compute instances list | grep ${node})" 265 | if [[ "${result}" == "${node}" ]]; then 266 | return 0 267 | fi 268 | return 1 269 | } 270 | 271 | # Returns 1 if the given firewall rule already exists, otherwise 0 272 | # @param {string} Name of the firewall rule to lookup 273 | # @return 1 if the given firewall rule already exists, otherwise 0 274 | firewall_rule_exists() { 275 | declare -r rule=$1 276 | declare -r result="$(gcloud compute firewall-rules list --format=value\(name\) | grep ${rule})" 277 | if [[ "${result}" == "${rule}" ]]; then 278 | return 1 279 | fi 280 | return 0 281 | } 282 | 283 | # Creates or destroys a firewall rule. 284 | # @param {string} the action to be performed, either "create" or "delete" 285 | # @param {string} the name of the service for which the rule is being created 286 | # @param {boolean} target only the node of the deployment if 1, otherwise 287 | # rule will target all nodes in the cluster 288 | manage_firewall_rule() { 289 | declare -r action=$1 290 | declare -r service=$2 291 | declare -r create_node_tag="${3:-0}" 292 | declare -r deployment="$(generate_deployment_name_for_service ${service})" 293 | 294 | declare -r node="$(get_hostport_deployment_node ${deployment})" 295 | validate_gcloud_node "${node}" 296 | if [ $? -ne 0 ]; then 297 | echoerr "Failed to create a firewall rule because the node ${node}" \ 298 | "isn't in your gcloud instance list. Run 'gcloud init' and" \ 299 | "select the project and zone containing the Kubernetes cluster." \ 300 | "Then run 'kubehost create-firewall ${service}'." 301 | return 0 302 | fi 303 | 304 | declare -r service_port="$(kubectl get service ${service} -o=jsonpath={.spec.ports[0].port})" 305 | declare -r service_protocol="$(kubectl get service ${service} -o=jsonpath={.spec.ports[0].protocol})" 306 | declare -r namespace="$(kubectl get service ${service} -o=jsonpath={.metadata.namespace})" 307 | 308 | # Get the GKE instance tag for this cluster 309 | declare -r gke_tag="$(gcloud compute instances list --filter=name=\(\"${node}\"\) --flatten=tags.items --format=value\(tags.items\) | grep 'gke.*node')" 310 | local tag="${gke_tag}" 311 | if [ "${create_node_tag}" -ne 0 ]; then 312 | tag="${namespace}-${service}" 313 | fi 314 | declare -r fwname="${namespace}-${service}-rule" 315 | if [[ "${action}" == "create" ]]; then 316 | firewall_rule_exists "${fwname}" 317 | if [ $? -ne 0 ]; then 318 | echoerr "Firewall rule ${fwname} already exists, not recreating." 319 | return 1 320 | fi 321 | echoerr "Creating ingress firewall rule from ${service_protocol}:${service_port} to instances with tag ${tag}." 322 | if [ "${create_node_tag}" -ne 0 ]; then 323 | gcloud compute instances add-tags "${node}" --tags "${tag}" 324 | fi 325 | gcloud compute firewall-rules create "${fwname}" --allow "${service_protocol}:${service_port}" --target-tags="${tag}" 326 | else 327 | echoerr "Deleting firewall rule." 328 | if [ "${create_node_tag}" -ne 0 ]; then 329 | gcloud compute instances remove-tags "${node}" --tags "${tag}" --quiet 330 | fi 331 | gcloud compute firewall-rules delete "${fwname}" --quiet 332 | fi 333 | } 334 | 335 | demo_cmd() { 336 | declare -r cmd=$1 337 | local yellow darkbg normal 338 | yellow=$(tput setaf 2) 339 | darkbg=$(tput setab 0) 340 | normal=$(tput sgr0) 341 | cur_ctx_fg="${KUBECTX_CURRENT_FGCOLOR:-$yellow}" 342 | cur_ctx_bg="${KUBECTX_CURRENT_BGCOLOR:-$darkbg}" 343 | 344 | # Prints the command 345 | echo "${cur_ctx_bg}${cur_ctx_fg} ${cmd}${normal}" 346 | 347 | # Evaluates the command 348 | ${cmd} 349 | } 350 | 351 | demo() { 352 | demo_cmd "kubectl run hello --image gcr.io/google-samples/hello-app:1.0 --port 8080" 353 | demo_cmd "kubectl expose deployment hello --port 80 --target-port 8080 --name hello-service" 354 | demo_cmd "$0 bind hello-service" 355 | } 356 | 357 | demo_cleanup() { 358 | demo_cmd "$0 unbind hello-service" 359 | demo_cmd "kubectl delete service hello-service" 360 | demo_cmd "kubectl delete deployment hello" 361 | } 362 | 363 | function main() { 364 | # Process optional arguments 365 | local skipfirewall=0 366 | local firewallnodeonly=0 367 | args=() 368 | while [ $# -gt 0 ]; do 369 | case $1 in 370 | -s|--skip-firewall) skipfirewall=1; shift 1 ;; 371 | --firewall-node-only) firewallnodeonly=1; shift 1 ;; 372 | -h|--help) usage; exit 1 ;; 373 | -*) echo "unknown option: $1" >&2; exit 1 ;; 374 | *) args+=($1); shift 1 ;; 375 | esac 376 | done 377 | 378 | # Compulsory arguments 379 | action="${args[0]}" 380 | service="${args[1]}" 381 | 382 | case "${action}" in 383 | "demo") 384 | demo 385 | exit 0 386 | ;; 387 | "demo_cleanup") 388 | demo_cleanup 389 | exit 0 390 | ;; 391 | "version") 392 | echo "kubehost version 1.0" 393 | exit 0 394 | ;; 395 | esac 396 | 397 | if [[ ! "${service}" ]]; then 398 | usage 399 | exit 1 400 | fi 401 | 402 | case "${action}" in 403 | "bind") 404 | validate_service_for_bind "${service}" 405 | declare -r deployment="$(expose_service $service)" 406 | sleep 1 407 | wait_deployment_available "${deployment}" 408 | if [ "${skipfirewall}" -ne 1 ]; then 409 | manage_firewall_rule "create" "${service}" "${firewallnodeonly}" 410 | fi 411 | declare -r ip="$(get_hostport_deployment_ip ${deployment})" 412 | echo "Service exposed on ${ip}" 413 | ;; 414 | "create-firewall") 415 | manage_firewall_rule "create" "${service}" 416 | ;; 417 | "delete-firewall") 418 | manage_firewall_rule "delete" "${service}" 419 | ;; 420 | "unbind") 421 | declare -r deployment="$(generate_deployment_name_for_service ${service})" 422 | if [ "${skipfirewall}" -ne 1 ]; then 423 | manage_firewall_rule "delete" "${service}" 424 | fi 425 | kubectl delete deployment "${deployment}" 426 | ;; 427 | "getip") 428 | declare -r deployment="$(generate_deployment_name_for_service ${service})" 429 | declare -r ip="$(get_hostport_deployment_ip ${deployment})" 430 | echo "Service exposed on ${ip}" 431 | ;; 432 | "upgrade") 433 | validate_service_for_upgrade "${service}" 434 | kubectl patch services ${service} --type='json' -p='[{"op": "replace", "path": "/spec/type", "value":"LoadBalancer"}]' 435 | declare -r ip="$(get_external_ip ${service})" 436 | echo "Service converted to LoadBalancer type and exposed on ${ip}" 437 | $0 unbind ${service} 438 | ;; 439 | "downgrade") 440 | validate_service_for_downgrade "${service}" 441 | kubectl patch services ${service} --type='json' -p='[{"op": "replace", "path": "/spec/type", "value":"ClusterIP"},{"op": "remove", "path": "/spec/ports/0/nodePort"}]' 442 | $0 bind ${service} 443 | ;; 444 | *) 445 | usage 446 | ;; 447 | esac 448 | } 449 | 450 | main $@ 451 | --------------------------------------------------------------------------------