зеркало из https://github.com/Azure/draft-classic.git
ref(docs): updated getting started with latest draft, added gotchas
This commit is contained in:
zdeptawa
Родитель
138abd153f
Коммит
99e3bb1063
|
|
@ -1,8 +1,8 @@
|
|||
# Getting Started
|
||||
|
||||
This document shows how to deploy a "Hello World" app with Draft. If you haven't done so already, be sure you have Draft installed according to the [Installation Guide][Installation Guide].
|
||||
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.
|
||||
|
||||
## App setup
|
||||
## Application Setup
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -12,19 +12,20 @@ $ cd examples/example-python
|
|||
|
||||
## Draft Create
|
||||
|
||||
We need some "scaffolding" to deploy our app 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`:
|
||||
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`:
|
||||
|
||||
```shell
|
||||
$ draft create
|
||||
--> Draft detected the primary language as Python with 97.267760% certainty.
|
||||
--> Draft detected Python (96.739130%)
|
||||
--> Ready to sail
|
||||
$ ls -a
|
||||
.draftignore Dockerfile app.py chart/ draft.toml requirements.txt
|
||||
.dockerignore .draftignore app.py draft.toml
|
||||
.draft-tasks.toml Dockerfile charts/ requirements.txt
|
||||
```
|
||||
|
||||
The `chart/` 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`. And to align with the service values in `chart/values.yaml`, this Dockerfile exposes port 80 from the container.
|
||||
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.
|
||||
|
||||
The `draft.toml` file contains basic configuration about the application like the name, the repository, which namespace it will be deployed to, and whether to deploy the app automatically when local files change.
|
||||
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.
|
||||
|
||||
```shell
|
||||
$ cat draft.toml
|
||||
|
|
@ -35,59 +36,102 @@ $ cat draft.toml
|
|||
wait = true
|
||||
watch = false
|
||||
watch-delay = 2
|
||||
override-ports = ["8080:8080", "9229:9229"]
|
||||
auto-connect = false
|
||||
auto-connect = false
|
||||
dockerfile = ""
|
||||
chart = ""
|
||||
```
|
||||
|
||||
See [DEP 6](reference/dep-006.md) for more information and available configuration on the `draft.toml`.
|
||||
See [dep-006.md][dep006] for more information and available configuration on the `draft.toml` file.
|
||||
|
||||
A `.draftignore` file is created as well 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).
|
||||
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).
|
||||
|
||||
```shell
|
||||
$ cat .draftignore
|
||||
*.swp
|
||||
*.tmp
|
||||
*.temp
|
||||
.git*
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```shell
|
||||
$ cat .dockerignore
|
||||
Dockerfile
|
||||
draft.toml
|
||||
charts/
|
||||
```
|
||||
|
||||
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` (`post-delete` tasks). This file is empty by default. See [dep-008.md][dep008] for more information and available configuration on the `.draft-tasks.toml` file.
|
||||
|
||||
## Draft Up
|
||||
|
||||
Now we're ready to deploy this app to a Kubernetes cluster. Draft handles these tasks with one `draft up` command:
|
||||
Now we're ready to deploy this application to a Kubernetes cluster. Draft handles these tasks with one `draft up` command:
|
||||
|
||||
- reads configuration from `draft.toml`
|
||||
- compresses the `chart/` directory and the application directory as two separate tarballs
|
||||
- compresses the `charts/` directory and the application directory as two separate tarballs
|
||||
- builds the image using `docker`
|
||||
- `docker` pushes the image to the registry specified in `draft.toml` (or in `draft config get registry`, if set)
|
||||
- `draft` instructs helm to install the chart, referencing the image just built
|
||||
- instructs `docker` to push the image to the registry specified in `draft.toml` (or in `draft config get registry`, if set)
|
||||
- instructs `helm` to install the chart, referencing the image just built
|
||||
|
||||
```shell
|
||||
$ draft up
|
||||
Draft Up Started: 'example-python'
|
||||
example-python: Building Docker Image: SUCCESS ⚓ (73.0991s)
|
||||
example-python: Pushing Docker Image: SUCCESS ⚓ (69.1425s)
|
||||
example-python: Releasing Application: SUCCESS ⚓ (0.6875s)
|
||||
example-python: Build ID: 01BSY5R8J45QHG9D3B17PAXMGN
|
||||
Draft Up Started: 'example-python': 01BSY5R8J45QHG9D3B17PAXMGN
|
||||
example-python: Building Docker Image: SUCCESS ⚓ (52.1337s)
|
||||
example-python: Releasing Application: SUCCESS ⚓ (0.5309s)
|
||||
Inspect the logs with `draft logs 01BSY5R8J45QHG9D3B17PAXMGN`
|
||||
```
|
||||
|
||||
## Interact with the Deployed App
|
||||
> 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`.
|
||||
|
||||
Now that the application has been deployed, we can connect to our app.
|
||||
To ensure your application deployed as expected, run `kubectl get pods` and take a look at the output.
|
||||
|
||||
```shell
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
example-python-python-6755c4944d-zbgvj 1/1 Running 0 5s
|
||||
```
|
||||
|
||||
> 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)`.
|
||||
|
||||
> INFO: For more information on installing and configuring Minikube for use with Draft, check out [the Minikube installation guide here](install-minikube.md).
|
||||
|
||||
## Interact with the Deployed Application
|
||||
|
||||
Now that the application has been deployed, we can connect to it using `draft connect`.
|
||||
|
||||
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.
|
||||
|
||||
```shell
|
||||
$ draft connect
|
||||
Connect to python:8080 on localhost:8080
|
||||
172.17.0.1 - - [13/Sep/2017 19:10:09] "GET / HTTP/1.1" 200 -
|
||||
Connect to python:8080 on localhost:54794
|
||||
[python]: * Environment: production
|
||||
[python]: WARNING: Do not use the development server in a production environment.
|
||||
[python]: Use a production WSGI server instead.
|
||||
[python]: * Debug mode: off
|
||||
[python]: * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
`draft connect` is the command 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, while also streaming the logs from all containers.
|
||||
> 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.
|
||||
|
||||
In another terminal window, we can connect to our app using the address displayed from `draft connect`'s output.
|
||||
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.
|
||||
|
||||
```shell
|
||||
$ curl localhost:8080
|
||||
$ curl localhost:54794
|
||||
Hello, World!
|
||||
```
|
||||
|
||||
Once you're done playing with this app, cancel out of the `draft connect` session using CTRL+C.
|
||||
> IMPORTANT: Your local port will likely be different than the one seen here.
|
||||
|
||||
> Note that you can use the flag `draft up --auto-connect` in order to have the application automatically connect once the deployment is done.
|
||||
> NOTE: If `localhost` does not resolve on your system, try `curl 127.0.0.1:<PORT>` instead.
|
||||
|
||||
> You can customize the local ports for the `draft connect` command either through the `-p` flag or through the `override-ports` field in `draft.toml`. More info in [dep-007.md][dep007]
|
||||
Once you're done checking the application out, you can cancel out of the `draft connect` session using `CTRL+C`.
|
||||
|
||||
## Update the App
|
||||
> NOTE: You can use the flag `draft up --auto-connect` in order to have the application automatically connect once the deployment is done.
|
||||
|
||||
> 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].
|
||||
|
||||
## Update the Application
|
||||
|
||||
Now, let's change the output in `app.py` to output "Hello, Draft!" instead:
|
||||
|
||||
|
|
@ -112,26 +156,65 @@ When we call `draft up` again, Draft determines that the Helm release already ex
|
|||
|
||||
```shell
|
||||
$ draft up
|
||||
Draft Up Started: 'example-python'
|
||||
example-python: Building Docker Image: SUCCESS ⚓ (13.0127s)
|
||||
example-python: Pushing Docker Image: SUCCESS ⚓ (16.0272s)
|
||||
example-python: Releasing Application: SUCCESS ⚓ (0.5533s)
|
||||
example-python: Build ID: 01BSYA4MW4BDNAPG6VVFWEPTH8
|
||||
Draft Up Started: 'example-python': 01CEQ5H21BWSR5M8HTJ5BVXPYW
|
||||
example-python: Building Docker Image: SUCCESS ⚓ (1.0010s)
|
||||
example-python: Releasing Application: SUCCESS ⚓ (2.1236s)
|
||||
Inspect the logs with `draft logs 01CEQ5H21BWSR5M8HTJ5BVXPYW`
|
||||
```
|
||||
|
||||
We should notice a significant faster build time here. This is because Docker is caching unchanged layers and only compiling layers that need to be re-built in the background.
|
||||
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.
|
||||
|
||||
## Great Success!
|
||||
|
||||
Now when we run `draft connect` and open the local URL using `curl` or our browser, we can see our app has been updated!
|
||||
We can run `draft connect` again to set up a proxy to our application:
|
||||
|
||||
```shell
|
||||
$ curl localhost:8080
|
||||
$ draft connect
|
||||
Connect to python:8080 on localhost:54961
|
||||
[python]: * Environment: production
|
||||
[python]: WARNING: Do not use the development server in a production environment.
|
||||
[python]: Use a production WSGI server instead.
|
||||
[python]: * Debug mode: off
|
||||
[python]: * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
$ curl localhost:54961
|
||||
Hello, Draft!
|
||||
```
|
||||
|
||||
[Installation Guide]: ../README.md#installation
|
||||
[Helm]: https://github.com/kubernetes/helm
|
||||
[Kubernetes]: https://kubernetes.io/
|
||||
[Python]: https://www.python.org/
|
||||
[dep007]: reference/dep-007.md
|
||||
We can see the application updated successfully!
|
||||
|
||||
## Draft Delete
|
||||
|
||||
If you're done testing this application, you can terminate and remove it from your Kubernetes cluster. To do so, run `draft delete`:
|
||||
|
||||
```shell
|
||||
$ draft delete
|
||||
app 'example-python' deleted
|
||||
```
|
||||
|
||||
If you run `kubectl get pods` shortly after, you should see your application `STATUS` is `Terminating`:
|
||||
|
||||
```shell
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
example-python-python-688fcf849f-8ddh7 1/1 Terminating 0 5m
|
||||
```
|
||||
|
||||
Once the termination completes, a `kubectl get pods` will show that the application no longer exists in your Kubernetes cluster:
|
||||
|
||||
```shell
|
||||
$ kubectl get pods
|
||||
No resources found.
|
||||
```
|
||||
|
||||
> 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.
|
||||
|
||||
> INFO: The `draft delete` command does not any image(s) created for the deployment within your Docker registry.
|
||||
|
||||
[dep006]: reference/dep-006.md
|
||||
[dep007]: reference/dep-007.md
|
||||
[dep008]: reference/dep-008.md
|
||||
Загрузка…
Ссылка в новой задаче