|
| 1 | +--- |
| 2 | +title: Connecting to your app |
| 3 | +description: Learn how to connect to your application. |
| 4 | +weight: 13 |
| 5 | +--- |
| 6 | + |
| 7 | +This topic guide shows you how to connect to your application deployed to SpinKube, including how to |
| 8 | +use port-forwarding for local development, or Ingress rules for a production setup. |
| 9 | + |
| 10 | +## Run the sample application |
| 11 | + |
| 12 | +Let's deploy a sample application to your Kubernetes cluster. We will use this application |
| 13 | +throughout the tutorial to demonstrate how to connect to it. |
| 14 | + |
| 15 | +Refer to the [quickstart guide]({{< ref "quickstart" >}}) if you haven't set up a Kubernetes cluster |
| 16 | +yet. |
| 17 | + |
| 18 | +```shell |
| 19 | +kubectl apply -f https://raw.githubusercontent.com/spinkube/spin-operator/main/config/samples/simple.yaml |
| 20 | +``` |
| 21 | + |
| 22 | +When SpinKube deploys the application, it creates a Kubernetes Service that exposes the application |
| 23 | +to the cluster. You can check the status of the deployment with the following command: |
| 24 | + |
| 25 | +```shell |
| 26 | +kubectl get services |
| 27 | +``` |
| 28 | + |
| 29 | +You should see a service named `simple-spinapp` with a type of `ClusterIP`. This means that the |
| 30 | +service is only accessible from within the cluster. |
| 31 | + |
| 32 | +```shell |
| 33 | +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE |
| 34 | +simple-spinapp ClusterIP 10.43.152.184 <none> 80/TCP 1m |
| 35 | +``` |
| 36 | + |
| 37 | +We will use this service to connect to your application. |
| 38 | + |
| 39 | +## Port forwarding |
| 40 | + |
| 41 | +This option is useful for debugging and development. It allows you to forward a local port to the |
| 42 | +service. |
| 43 | + |
| 44 | +Forward port 8083 to the service so that it can be reached from your computer: |
| 45 | + |
| 46 | +```shell |
| 47 | +kubectl port-forward svc/simple-spinapp 8083:80 |
| 48 | +``` |
| 49 | + |
| 50 | +You should be able to reach it from your browser at [http://localhost:8083](http://localhost:8083): |
| 51 | + |
| 52 | +```shell |
| 53 | +curl http://localhost:8083 |
| 54 | +``` |
| 55 | + |
| 56 | +You should see a message like "Hello world from Spin!". |
| 57 | + |
| 58 | +This is one of the simplest ways to test your application. However, it is not suitable for |
| 59 | +production use. The next section will show you how to expose your application to the internet using |
| 60 | +an Ingress controller. |
| 61 | + |
| 62 | +## Ingress |
| 63 | + |
| 64 | +Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster. |
| 65 | +Traffic routing is controlled by rules defined on the Ingress resource. |
| 66 | + |
| 67 | +Here is a simple example where an Ingress sends all its traffic to one Service: |
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | +(source: [Kubernetes |
| 72 | +documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/)) |
| 73 | + |
| 74 | +An Ingress may be configured to give applications externally-reachable URLs, load balance traffic, |
| 75 | +terminate SSL / TLS, and offer name-based virtual hosting. An Ingress controller is responsible for |
| 76 | +fulfilling the Ingress, usually with a load balancer, though it may also configure your edge router |
| 77 | +or additional frontends to help handle the traffic. |
| 78 | + |
| 79 | +### Prerequisites |
| 80 | + |
| 81 | +You must have an [Ingress |
| 82 | +controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) to satisfy |
| 83 | +an Ingress rule. Creating an Ingress rule without a controller has no effect. |
| 84 | + |
| 85 | +Ideally, all Ingress controllers should fit the reference specification. In reality, the various |
| 86 | +Ingress controllers operate slightly differently. Make sure you review your Ingress controller's |
| 87 | +documentation to understand the specifics of how it works. |
| 88 | + |
| 89 | +[ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/) is a popular Ingress controller, |
| 90 | +so we will use it in this tutorial: |
| 91 | + |
| 92 | +```shell |
| 93 | +helm upgrade --install ingress-nginx ingress-nginx \ |
| 94 | + --repo https://kubernetes.github.io/ingress-nginx \ |
| 95 | + --namespace ingress-nginx --create-namespace |
| 96 | +``` |
| 97 | + |
| 98 | +Wait for the ingress controller to be ready: |
| 99 | + |
| 100 | +```shell |
| 101 | +kubectl wait --namespace ingress-nginx \ |
| 102 | + --for=condition=ready pod \ |
| 103 | + --selector=app.kubernetes.io/component=controller \ |
| 104 | + --timeout=120s |
| 105 | +``` |
| 106 | + |
| 107 | +### Check the Ingress controller's external IP address |
| 108 | + |
| 109 | +If your Kubernetes cluster is a "real" cluster that supports services of type `LoadBalancer`, it |
| 110 | +will have allocated an external IP address or FQDN to the ingress controller. |
| 111 | + |
| 112 | +Check the IP address or FQDN with the following command: |
| 113 | + |
| 114 | +```shell |
| 115 | +kubectl get service ingress-nginx-controller --namespace=ingress-nginx |
| 116 | +``` |
| 117 | + |
| 118 | +It will be the `EXTERNAL-IP` field. If that field shows `<pending>`, this means that your Kubernetes |
| 119 | +cluster wasn't able to provision the load balancer. Generally, this is because it doesn't support |
| 120 | +services of type `LoadBalancer`. |
| 121 | + |
| 122 | +Once you have the external IP address (or FQDN), set up a DNS record pointing to it. Refer to your |
| 123 | +DNS provider's documentation on how to add a new DNS record to your domain. |
| 124 | + |
| 125 | +You will want to create an A record that points to the external IP address. If your external IP |
| 126 | +address is `<EXTERNAL-IP>`, you would create a record like this: |
| 127 | + |
| 128 | +```shell |
| 129 | +A myapp.spinkube.local <EXTERNAL-IP> |
| 130 | +``` |
| 131 | + |
| 132 | +Once you've added a DNS record to your domain and it has propagated, proceed to create an ingress |
| 133 | +resource. |
| 134 | + |
| 135 | +### Create an Ingress resource |
| 136 | + |
| 137 | +Create an Ingress resource that routes traffic to the `simple-spinapp` service. The following |
| 138 | +example assumes that you have set up a DNS record for `myapp.spinkube.local`: |
| 139 | + |
| 140 | +```shell |
| 141 | +kubectl create ingress simple-spinapp --class=nginx --rule="myapp.spinkube.local/*=simple-spinapp:80" |
| 142 | +``` |
| 143 | + |
| 144 | +A couple notes about the above command: |
| 145 | + |
| 146 | +- `simple-spinapp` is the name of the Ingress resource. |
| 147 | +- `myapp.spinkube.local` is the hostname that the Ingress will route traffic to. This is the DNS |
| 148 | + record you set up earlier. |
| 149 | +- `simple-spinapp:80` is the Service that SpinKube created for us. The application listens for |
| 150 | + requests on port 80. |
| 151 | + |
| 152 | +Assuming DNS has propagated correctly, you should see a message like "Hello world from Spin!" when |
| 153 | +you connect to http://myapp.spinkube.local/. |
| 154 | + |
| 155 | +Congratulations, you are serving a public website hosted on a Kubernetes cluster! 🎉 |
| 156 | + |
| 157 | +### Connecting with kubectl port-forward |
| 158 | + |
| 159 | +This is a quick way to test your Ingress setup without setting up DNS records or on clusters without |
| 160 | +support for services of type `LoadBalancer`. |
| 161 | + |
| 162 | +Open a new terminal and forward a port from localhost port 8080 to the Ingress controller: |
| 163 | + |
| 164 | +```shell |
| 165 | +kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8080:80 |
| 166 | +``` |
| 167 | + |
| 168 | +Then, in another terminal, test the Ingress setup: |
| 169 | + |
| 170 | +```shell |
| 171 | +curl --resolve myapp.spinkube.local:8080:127.0.0.1 http://myapp.spinkube.local:8080/hello |
| 172 | +``` |
| 173 | + |
| 174 | +You should see a message like "Hello world from Spin!". |
| 175 | + |
| 176 | +If you want to see your app running in the browser, update your `/etc/hosts` file to resolve |
| 177 | +requests from `myapp.spinkube.local` to the ingress controller: |
| 178 | + |
| 179 | +```shell |
| 180 | +127.0.0.1 myapp.spinkube.local |
| 181 | +``` |
0 commit comments