github.com/SupersunnySea/draft@v0.16.0/docs/getting-started.md (about) 1 # Getting Started 2 3 This document shows how to deploy a "Hello World" application with Draft. If you haven't done so already, be sure you have Draft installed properly. This [Quickstart Guide](quickstart.md) is the perfect resource if you still need to install Draft. 4 5 ## Application Setup 6 7 There are multiple example applications included within the [examples directory](../examples). For this walkthrough, we'll be using the [python example application](../examples/example-python) which uses [Flask](http://flask.pocoo.org/) to provide a very simple Hello World webserver. 8 9 ```shell 10 $ cd examples/example-python 11 ``` 12 13 ## Draft Create 14 15 We need some "scaffolding" to deploy our application into a [Kubernetes](https://kubernetes.io/) cluster. Draft can create a [Helm](https://helm.sh/) chart, a `Dockerfile`, and a `draft.toml` with `draft create`: 16 17 ```shell 18 $ draft create 19 --> Draft detected Python (96.739130%) 20 --> Ready to sail 21 $ ls -a 22 .dockerignore .draftignore app.py draft.toml 23 .draft-tasks.toml Dockerfile charts/ requirements.txt 24 ``` 25 26 The `charts/` and `Dockerfile` assets created by Draft default to a basic Python configuration. This `Dockerfile` harnesses the [python:onbuild](https://hub.docker.com/_/python/) image, which will install the dependencies in `requirements.txt` and copy the current directory into `/usr/src/app`. To align with the `internalPort` service value in `charts/python/values.yaml`, this `Dockerfile` exposes port 8080 from the container. 27 28 The `draft.toml` file contains basic configuration details about the application like the name, the repository, which namespace it will be deployed to, and whether to deploy the application automatically when local files change. 29 30 ```shell 31 $ cat draft.toml 32 [environments] 33 [environments.development] 34 name = "example-python" 35 namespace = "default" 36 wait = true 37 watch = false 38 watch-delay = 2 39 auto-connect = false 40 dockerfile = "" 41 chart = "" 42 ``` 43 44 See [dep-006.md][dep006] for more information and available configuration on the `draft.toml` file. 45 46 A `.draftignore` file is created for elements we want to exclude tracking on `draft up` when watching for changes. The syntax is identical to [helm's .helmignore file](https://github.com/kubernetes/helm/blob/master/pkg/repo/repotest/testdata/examplechart/.helmignore). 47 48 ```shell 49 $ cat .draftignore 50 *.swp 51 *.tmp 52 *.temp 53 .git* 54 ``` 55 56 A [`.dockerignore`](https://docs.docker.com/engine/reference/builder/#dockerignore-file) file is created to ensure the docker context ignores files and directories that are not necessary. 57 58 ```shell 59 $ cat .dockerignore 60 Dockerfile 61 draft.toml 62 charts/ 63 ``` 64 65 A `.draft-tasks.toml` file is also created. This file allows you to configure tasks to be run before `draft up` (`pre-up` tasks), after `draft up` (`post-up` tasks), or after `draft delete` (`cleanup` tasks). This file is empty by default. See [dep-008.md][dep008] for more information and available configuration on the `.draft-tasks.toml` file. 66 67 ## Draft Up 68 69 Now we're ready to deploy this application to a Kubernetes cluster. Draft handles these tasks with one `draft up` command: 70 71 - reads configuration from `draft.toml` 72 - compresses the `charts/` directory and the application directory as two separate tarballs 73 - builds the image using `docker` 74 - instructs `docker` to push the image to the registry specified in `draft.toml` (or in `draft config get registry`, if set) 75 - instructs `helm` to install the chart, referencing the image just built 76 77 ```shell 78 $ draft up 79 Draft Up Started: 'example-python': 01BSY5R8J45QHG9D3B17PAXMGN 80 example-python: Building Docker Image: SUCCESS ⚓ (52.1337s) 81 example-python: Releasing Application: SUCCESS ⚓ (0.5309s) 82 Inspect the logs with `draft logs 01BSY5R8J45QHG9D3B17PAXMGN` 83 ``` 84 85 > NOTE: You might see a `WARNING: no registry has been set` message if no container registry has been configured in draft. You can set a container registry using the `draft config set registry docker.io/myusername` command. If you'd prefer to silence this warning instead, you can run `draft config set disable-push-warning 1`. 86 87 To ensure your application deployed as expected, run `kubectl get pods` and take a look at the output. 88 89 ```shell 90 $ kubectl get pods 91 NAME READY STATUS RESTARTS AGE 92 example-python-python-6755c4944d-zbgvj 1/1 Running 0 5s 93 ``` 94 95 > NOTE: If you're using Minikube and your `STATUS` shows an error such as `ErrImagePull` or `ImagePullBackOff`, make sure you've configured Draft to build images directly using Minikube's Docker daemon. You can do so by running `eval $(minikube docker-env)`. 96 97 > INFO: For more information on installing and configuring Minikube for use with Draft, check out [the Minikube installation guide here](install-minikube.md). 98 99 ## Interact with the Deployed Application 100 101 Now that the application has been deployed, we can connect to it using `draft connect`. 102 103 The `draft connect` command is used to interact with the application deployed on your cluster. It works by creating proxy connections to the ports exposed by the containers in your pod. It also streams the logs from all containers. 104 105 ```shell 106 $ draft connect 107 Connect to python:8080 on localhost:54794 108 [python]: * Environment: production 109 [python]: WARNING: Do not use the development server in a production environment. 110 [python]: Use a production WSGI server instead. 111 [python]: * Debug mode: off 112 [python]: * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) 113 ``` 114 115 > NOTE: The `WARNING: Do not use the development server in a production environment` message is coming from Flask. The message is in regard to Flask's built-in web server and can safely be ignored for our test purposes here. 116 117 In this example, you can see that `draft connect` has proxied port 8080 from our container to port 54794 on localhost. We can now open a browser window or another terminal window and connect to our application using the address and port displayed from `draft connect`'s output. 118 119 ```shell 120 $ curl localhost:54794 121 Hello, World! 122 ``` 123 124 > IMPORTANT: Your local port will likely be different than the one seen here. 125 126 > NOTE: If `localhost` does not resolve on your system, try `curl 127.0.0.1:<PORT>` instead. 127 128 Once you're done checking the application out, you can cancel out of the `draft connect` session using `CTRL+C`. 129 130 > NOTE: You can use the flag `draft up --auto-connect` in order to have the application automatically connect once the deployment is done. 131 132 > INFO: You can also customize the local ports for the `draft connect` command by using the `-p` flag or through the `override-ports` field in `draft.toml`. More information on this can be found in [dep-007.md][dep007]. 133 134 ## Update the Application 135 136 Now, let's change the output in `app.py` to output "Hello, Draft!" instead: 137 138 ```shell 139 $ cat <<EOF > app.py 140 from flask import Flask 141 142 app = Flask(__name__) 143 144 @app.route("/") 145 def hello(): 146 return "Hello, Draft!\n" 147 148 if __name__ == "__main__": 149 app.run(host='0.0.0.0', port=8080) 150 EOF 151 ``` 152 153 ## Draft Up(grade) 154 155 When we call `draft up` again, Draft determines that the Helm release already exists and will perform a `helm upgrade` rather than attempting another `helm install`: 156 157 ```shell 158 $ draft up 159 Draft Up Started: 'example-python': 01CEQ5H21BWSR5M8HTJ5BVXPYW 160 example-python: Building Docker Image: SUCCESS ⚓ (1.0010s) 161 example-python: Releasing Application: SUCCESS ⚓ (2.1236s) 162 Inspect the logs with `draft logs 01CEQ5H21BWSR5M8HTJ5BVXPYW` 163 ``` 164 165 We should notice a significantly faster build time here. This is because Docker is caching unchanged layers and only compiling layers that need to be rebuilt in the background. 166 167 ## Great Success! 168 169 We can run `draft connect` again to set up a proxy to our application: 170 171 ```shell 172 $ draft connect 173 Connect to python:8080 on localhost:54961 174 [python]: * Environment: production 175 [python]: WARNING: Do not use the development server in a production environment. 176 [python]: Use a production WSGI server instead. 177 [python]: * Debug mode: off 178 [python]: * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) 179 ``` 180 181 Once we have the address and port, we can connect again using `curl` in a new terminal window or by browsing to the host and port in a browser window: 182 183 ```shell 184 $ curl localhost:54961 185 Hello, Draft! 186 ``` 187 188 We can see the application updated successfully! 189 190 ## Draft Delete 191 192 If you're done testing this application, you can terminate and remove it from your Kubernetes cluster. To do so, run `draft delete`: 193 194 ```shell 195 $ draft delete 196 app 'example-python' deleted 197 ``` 198 199 If you run `kubectl get pods` shortly after, you should see your application `STATUS` is `Terminating`: 200 201 ```shell 202 $ kubectl get pods 203 NAME READY STATUS RESTARTS AGE 204 example-python-python-688fcf849f-8ddh7 1/1 Terminating 0 5m 205 ``` 206 207 Once the termination completes, a `kubectl get pods` will show that the application no longer exists in your Kubernetes cluster: 208 209 ```shell 210 $ kubectl get pods 211 No resources found. 212 ``` 213 214 > IMPORTANT NOTE: The `draft delete` command should be run with **extreme care and caution** as it performs a termination and removal of the application from your Kubernetes cluster. 215 216 > INFO: The `draft delete` command does not any image(s) created for the deployment within your Docker registry. 217 218 [dep006]: reference/dep-006.md 219 [dep007]: reference/dep-007.md 220 [dep008]: reference/dep-008.md