Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

0.13 docs update: tutorials #4127

Merged
merged 16 commits into from
May 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 72 additions & 44 deletions docs/tutorials/your-first-project/1-initialize-a-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,21 @@ order: 1

# 1. Initialize a Project

With the Garden CLI [installed](../../basics/quickstart.md#step-1-install-garden), we'll kick off by configuring a simple example project for use with Garden.
With the Garden CLI [installed](../../basics/quickstart.md#step-1-install-garden), we'll kick off by configuring a
simple example project for use with Garden.

Start by cloning our repo and finding the example project:
Start by cloning our repo and finding the [example project](../../../examples/demo-project-start):

```sh
git clone https://github.com/garden-io/garden.git
cd garden/examples/demo-project-start
```

This directory contains two directories, with one container service each, `backend` and `frontend`. We'll first define a boilerplate Garden project, and then a Garden module for each of the services.
The example directory has two directories: `backend` and `frontend`. Each contains simple application with
a `Dockerfile`. We'll first define a boilerplate Garden project, and then Garden action configurations for each
application.

To initialize the project, we can use a helper command:
To initialize the project use a helper command:
Comment on lines -19 to +22
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


```sh
garden create project
Expand All @@ -35,55 +38,80 @@ providers:

We have one environment (`default`) and a single provider. We'll get back to this later.

Next, let's create module configs for each of our two modules, starting with `backend`.
Next, let's create action configs for each of our two applications, starting with `backend`.

```sh
cd backend
garden create module
cd ..
```
First we need to define `Build` and `Deploy` actions for the `backend` application. Let's use `container` action type.
Create an empty `backend.garden.yml` config file in the `backend` directory and add the following lines:

You'll get a suggestion to make it a `container` module. Pick that, and give it the default name as well. Then do the same for the `frontend` module:
```yaml
kind: Build
name: backend
description: Backend service container image
type: container

```sh
cd frontend
garden create module
cd ..
```
---

This is now enough configuration to build the project. Before we can deploy, we need to configure `services` in each module configuration, as well as set up a local cluster or connect to a remote cluster.
kind: Deploy
name: backend
description: Backend service container
type: container

# Reference to the Build action that builds the image to be deployed (defined above)
build: backend

# Action type specific config goes under the `spec` block
spec:
healthCheck:
httpGet:
path: /hello-backend
port: http
ports:
- name: http
containerPort: 8080
servicePort: 80
ingresses:
- path: /hello-backend
port: http
```

Starting with the former, go ahead and open the newly created `backend/garden.yml` file. Just to keep things simple for now, go ahead and append to the file the following:
Next, let's do the same for the `frontend` application:
Create a `frontend.garden.yml` config file in the `frontend` directory and add the following lines:

```yaml
services:
- name: backend
ports:
- name: http
containerPort: 8080
servicePort: 80
ingresses:
- path: /hello-backend
port: http
```
```sh
kind: Build
name: frontend
description: Frontend service container image
type: container

This is enough information for Garden to be able to deploy and expose the `backend` service. Now do the same for the `frontend` service, with the following block:
---

```yaml
services:
- name: frontend
ports:
- name: http
containerPort: 8080
ingresses:
- path: /hello-frontend
port: http
- path: /call-backend
port: http
dependencies:
- backend
kind: Deploy
name: frontend
description: Frontend service container
type: container

build: frontend
# Dependency section is used to specify action execution order. The frontend will be deployed after the backend is deployed.
# Dependency for the Build action is implicit.
dependencies:
- deploy.backend

spec:
ports:
- name: http
containerPort: 8080
healthCheck:
httpGet:
path: /hello-frontend
port: http
ingresses:
- path: /hello-frontend
port: http
- path: /call-backend
port: http
```

This does the same for the `frontend` service, with the addition of declaring a runtime dependency on the `backend` service.
Before deploying, you need to set up a local kubernetes cluster or connect to a remote cluster.
First you can try to deploy the project with the local kubernetes cluster.

Now, let's move on to our next section, and [connect to a Kubernetes cluster](./2-connect-to-a-cluster.md).
39 changes: 28 additions & 11 deletions docs/tutorials/your-first-project/3-deploy-and-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,43 @@ Now that you have your project and cluster set up, you can go ahead and deploy t
garden deploy
```

You should see your services come up. Next we can set up our first test. Similar to how you configured the `services` earlier, open the `frontend/garden.yml` config and add the following:
You should see your applications come up. Garden will print the statuses of the corresponding `Deploy` actions. Next we
can set up our first test. Similar to how you configured the `Deploy` actions earlier, open the `frontend/garden.yml`
config and add the following action configurations:

```yaml
tests:
- name: unit
args: [npm, test]
- name: integ
args: [npm, run, integ]
dependencies:
- frontend

--- # the yaml separator is necessary to delimit different actions

kind: Test
name: frontend-unit
type: container
build: frontend
spec:
args: [ npm, test ]

---

kind: Test
name: frontend-integ
type: container
build: frontend
dependencies:
- deploy.frontend # <- have the frontend service be running and up-to-date before the test
spec:
args: [ npm, run, integ ]
```

This defines two simple test suites. One simply runs the unit tests of the `frontend` service. The other runs a basic integration test that relies on the `frontend` service being up and running.
This defines two simple test suites. One simply runs the unit tests of the `frontend` application. The other runs a
basic integration test that relies on the `frontend` application being up and running.

Let's run them both:

```sh
garden test
```

You should see Garden ensuring that the services are up and running, and that both tests run successfully.
You should see Garden ensuring that the applications are up and running, and that both tests run successfully.

With that, we can move on from this simple example and on to [configuring your own project](./4-configure-your-project.md).
With that, we can move on from this simple example and on
to [configuring your own project](./4-configure-your-project.md).
32 changes: 21 additions & 11 deletions docs/tutorials/your-first-project/4-configure-your-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,30 @@ order: 4

# 4. Configure Your Project

With the basic example all set, we can start thinking about your own project. The steps will be similar, and some of the work you won't need to repeat.
With the basic example all set, we can start thinking about your own project. The steps will be similar, and some work
you won't need to repeat.

Garden is a powerful and flexible tool, and there are several things to learn along the way. We recommend the following to get going:
Garden is a powerful and flexible tool, and there are several things to learn along the way. We recommend the following
to get going:

1. Place the project configuration you created for the example, which will be all set to connect to your cluster, in your own project root.
2. Go through the [Using Garden](../../using-garden/README.md) documentation section. This will cover all the key concepts, and introduce all the moving parts, including the different module types that Garden supports.
3. Have a look at the [examples](https://github.com/garden-io/garden/tree/0.12.51/examples) folder in the Garden repository, which offers several usage examples that you can refer to while building out your project.
4. Set up your modules, getting them building and deploying, **one at a time**.
1. Place the project configuration you created for the example, which will be all set to connect to your cluster, in
your own project root.
2. Go through the [Using Garden](../../using-garden/README.md) documentation section. This will cover all the key
concepts, and introduce all the moving parts, including the different action kinds and types that Garden supports.
3. Have a look at the [examples](../../../examples) folder in the Garden repository, which offers several usage examples
that you can refer to while building out your project.
4. Configure your actions, get them building and deploying.
5. Make sure your whole project builds and deploys successfully.
6. Start thinking about tests. Garden excels at managing all the different test suites in your stack, especially integration and end-to-end tests that need to run inside your deployment environment.
7. Consider [running Garden in your CI](../../guides/using-garden-in-ci.md), to deploy preview environments and/or to test your project.
6. Start thinking about tests. Garden excels at managing all the different test suites in your stack, especially
integration and end-to-end tests that need to run inside your deployment environment.
7. Consider [running Garden in your CI](../../guides/using-garden-in-ci.md), to deploy preview environments and/or to
test your project.

In summary, **gradually put all the pieces together**, learn the details as you go, and use more and more features as you get comfortable.
In summary, **gradually put all the pieces together**, learn the details as you go, and use more and more features as
you get comfortable.

For a large, complex project, it might be good to start with a subset of it, so that you can start getting value out of Garden quickly.
For a large, complex project, it might be good to start with a subset of it, so that you can start getting value out of
Garden quickly.

Whatever your setup is, we're sure you'll be rewarded with an elegant, productive setup for testing and developing your system!
Whatever your setup is, we're sure you'll be rewarded with an elegant, productive setup for testing and developing your
system!
6 changes: 4 additions & 2 deletions docs/tutorials/your-first-project/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@ title: Your First Project
order: 1
---

This tutorial walks you through the first few steps of getting started with Garden using one of the Kubernetes plugins (local or remote).
This tutorial walks you through the first few steps of getting started with Garden using one of the Kubernetes plugins (
local or remote).

We'll go through:

Expand All @@ -12,7 +13,8 @@ We'll go through:
3. [Deploying and testing the project](./3-deploy-and-test.md)
4. How you can go from there and [configure your own project](./4-configure-your-project.md)

You'll need to have Garden installed to follow along with this guide. You'll find the instructions in our [Quickstart uigde](../../basics/quickstart.md).
You'll need to have Garden installed to follow along with this guide. You'll find the instructions in
our [Quickstart guide](../../basics/quickstart.md).

We also recommend quickly reading the [How Garden Works](../../basics/how-garden-works.md) page before carrying on.

Expand Down
2 changes: 1 addition & 1 deletion docs/using-garden/using-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ garden create module

### Creating an action

[//]: # "TODO"
See the [actions guide](./actions.md) to learn more about actions and how to create them.

## Remote sources

Expand Down