Skip to content

Commit

Permalink
docs: Tidy the navbar
Browse files Browse the repository at this point in the history 
And break up 'Getting Started'. This layout is inspired by Tilt's docs,
which are often mentioned as Good.
  • Loading branch information
@Callisto13
Callisto13 committed Feb 2, 2023
1 parent 1769dda commit 6e80bf4
Show file tree
Hide file tree
Showing 13 changed files with 208 additions and 180 deletions.
134 changes: 134 additions & 0 deletions website/docs/getting-started/deploy.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
title: 2. Deploy an Application
hide_title: true
---

# Part 2: Deploy an Application

Now that you have a feel for how to navigate the dashboard, let's deploy a new
application to explore further. In this section we will use the [podinfo](https://github.com/stefanprodan/podinfo) sample web application.

## Deploying podinfo

1. Clone or navigate back to your git repository where you have bootstrapped Flux, for example:

```
git clone https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra
```

1. Create a `GitRepository` Source for podinfo

```
flux create source git podinfo \
--url=https://github.com/stefanprodan/podinfo \
--branch=master \
--interval=30s \
--export > ./clusters/my-cluster/podinfo-source.yaml
```

1. Commit and push the `podinfo-source` to the `fleet-infra` repository

```
git add -A && git commit -m "Add podinfo source"
git push
```

1. Create a `kustomization` to build and apply the podinfo manifest

```
flux create kustomization podinfo \
--target-namespace=flux-system \
--source=podinfo \
--path="./kustomize" \
--prune=true \
--interval=5m \
--export > ./clusters/my-cluster/podinfo-kustomization.yaml
```

1. Commit and push the `podinfo-kustomization` to the `fleet-infra` repository

```
git add -A && git commit -m "Add podinfo kustomization"
git push
```

## View the application in Weave GitOps

Flux will detect the updated `fleet-infra` and add podinfo. If we navigate back to the [dashboard](http://localhost:9001/) you should see the podinfo application appear.

![Applications summary view showing Flux System, Weave GitOps and Podinfo](/img/dashboard-applications-with-podinfo.png)

Click on podinfo and you will see details about the deployment, including that there is 1 pod available.

![Applications details view for podinfo showing 1 pods](/img/dashboard-podinfo-details.png)

## Customize podinfo

To customize a deployment from a repository you don’t control, you can use Flux in-line patches. The following example shows how to use in-line patches to change the podinfo deployment.

1. Add the `patches` section as shown below to the field spec of your podinfo-kustomization.yaml file so it looks like this:

```yaml title="./clusters/my-cluster/podinfo-kustomization.yaml"
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 60m0s
path: ./kustomize
prune: true
sourceRef:
kind: GitRepository
name: podinfo
targetNamespace: flux-system
// highlight-start
patches:
- patch: |-
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
name: podinfo
spec:
minReplicas: 3
target:
name: podinfo
kind: HorizontalPodAutoscaler
// highlight-end
```

1. Commit and push the podinfo-kustomization.yaml changes:

```
git add -A && git commit -m "Increase podinfo minimum replicas"
git push
```

3. Navigate back to the dashboard and you will now see 2 newly created pods

![Applications details view for podinfo showing 3 pods](/img/dashboard-podinfo-updated.png)


## Suspend updates

Suspending updates to a kustomization allows you to directly edit objects applied from a kustomization, without your changes being reverted by the state in Git.

To suspend updates for a kustomization, from the details page, click on the suspend button at the top, and you should see it be suspended:

![Podinfo details showing Podinfo suspended](/img/dashboard-podinfo-details-suspended.png)

This shows in the applications view with a yellow warning status indicating it is now suspended

![Applications summary view showing Podinfo suspended](/img/dashboard-podinfo-suspended.png)

To resume updates, go back to the details page, click the resume button, and after a few seconds reconsolidation will continue:

![Applications details view for podinfo being resumed](/img/dashboard-podinfo-updated.png)

## Complete!

Congratulations 🎉🎉🎉

You've now completed the getting started guide. We would welcome any and all [feedback](feedback-and-telemetry.md) on your experience.
16 changes: 16 additions & 0 deletions website/docs/getting-started/intro.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: Getting Started
hide_title: true
---

# Getting Started with Weave GitOps

This hands-on guide will introduce you to the basics of the GitOps Dashboard web UI, to help you understand the state of your system, before deploying a new application to your cluster. It is adapted from this guide - [Flux - Getting Started](https://fluxcd.io/docs/get-started/).

If you haven't already, be sure to check out our [introduction](../intro.mdx) to Weave GitOps and our [installation docs](../installation/index.mdx).

## TL;DR: Highlights

- **Applications view** - allows you to quickly understand the state of your deployments across a cluster at a glance. It shows summary information from `kustomization` and `helmrelease` objects.
- **Sources view** - shows the status of resources which are synchronizing content from where you have declared the desired state of your system, for example Git repositories. This shows summary information from `gitrepository`, `helmrepository` and `bucket` objects.
- **Flux Runtime view** - provides status on the GitOps engine continuously reconciling your desired and live state. It shows your installed GitOps Toolkit Controllers and their version.
163 changes: 10 additions & 153 deletions website/docs/getting-started.mdx → website/docs/getting-started/ui.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,25 @@
---
title: Getting Started
title: 1. Explore the GitOps UI
hide_title: true
---

# Getting Started with Weave GitOps

This hands-on guide will introduce you to the basics of the GitOps Dashboard web UI, to help you understand the state of your system, before deploying a new application to your cluster. It is adapted from this guide - [Flux - Getting Started](https://fluxcd.io/docs/get-started/).

If you haven't already, be sure to check out our [introduction](./intro.mdx) to Weave GitOps and our [installation docs](./installation/index.mdx).

## TL;DR: Highlights

- **Applications view** - allows you to quickly understand the state of your deployments across a cluster at a glance. It shows summary information from `kustomization` and `helmrelease` objects.
- **Sources view** - shows the status of resources which are synchronizing content from where you have declared the desired state of your system, for example Git repositories. This shows summary information from `gitrepository`, `helmrepository` and `bucket` objects.
- **Flux Runtime view** - provides status on the GitOps engine continuously reconciling your desired and live state. It shows your installed GitOps Toolkit Controllers and their version.

## Part 1 - Weave GitOps overview
# Part 1: Explore the GitOps UI

Weave GitOps provides insights into your application deployments, and makes continuous delivery with GitOps easier to adopt and scale across your teams. We will now login to the dashboard web UI and start to explore the state of our GitOps deployments.

### Login to the GitOps Dashboard
## Login to the GitOps Dashboard

1. Expose the service running on the cluster

```
kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001
```

1. [Open the dashboard](http://localhost:9001/) and login using either the cluster user or OIDC based on your [configuration](./configuration/securing-access-to-the-dashboard.mdx). If you followed the example above, the username will be `admin`, and the password is the non-encrypted value you provided as $PASSWORD.
1. [Open the dashboard](http://localhost:9001/) and login using either the cluster user or OIDC based on your [configuration](../configuration/securing-access-to-the-dashboard.mdx). If you followed the example above, the username will be `admin`, and the password is the non-encrypted value you provided as $PASSWORD.

![Weave GitOps login screen](/img/dashboard-login.png)

### Applications view
## Applications view

When you login to the dashboard you are brought to the Applications view, which allows you to quickly understand the state of your deployments across a cluster at a glance. It shows summary information from `kustomization` and `helmrelease` objects.

Expand All @@ -47,7 +35,7 @@ You can search for and filter objects by `Name` by clicking the magnifying glass

Clicking the Name of an object will take you to a detailed view for the given Kustomization or HelmRelease. Which we will explore in a moment.

### The Sources view
## The Sources view

Clicking on Sources in the left hand menu will bring you to the Sources view. This view shows you where flux pulls its application definitions from, for example Git repositories, and the current state of that synchronization. This shows summary information from `gitrepository`, `helmrepository`, `helmchart` and `bucket` objects.

Expand All @@ -60,12 +48,11 @@ In the above screenshot you can see:

The table view again shows summary status information so you can see whether Flux has been able to successfully pull from a given source and which specific commit was last detected. It shows key information like the `Interval`, namely how frequently Flux will check for updates in a given source location. You can apply filtering as per the Applications view, can click the `URL` to navigate to a given source i.e. a repository in GitHub, or the `Name` of a `Source` to view more details about it.


### The Flux Runtime view
## The Flux Runtime view

Clicking on `Flux Runtime` provides information on the GitOps engine, which is continuously reconciling your desired and live state. It provides two different tabs: controllers and CRDs.

#### Controllers
### Controllers

The controllers tab shows your installed GitOps Toolkit Controllers and their version.

Expand All @@ -81,7 +68,7 @@ For a full description of the controllers, see [GitOps ToolKit components](https

From this view you can see whether the controllers are healthy and which version of a given component is currently deployed.

#### CRDs
### CRDs

The CRD tab lists the custom resources that the GitOps Toolkit Controllers use. This helps you see what resources you will be able to create.

Expand Down Expand Up @@ -112,139 +99,9 @@ Underneath the summary information are four tabs:
**Yaml tab**
![Application detail view showing the yaml display](/img/dashboard-application-yaml.png)

#### Source details view
### Source details view
Finally lets look at the Source in more detail - go back to the Details tab, and click `GitRepository/flux-system` from the summary at the top of the page.

![Source detail view showing details for an object](/img/dashboard-source-flux.png)

As with an Application detail view, you can see key information about how the resource is defined. Then beneath alongside the Events tab, is a Related Automations view. This shows all the `kustomization` objects which have this object as their Source.


## Part 2 - Deploying and viewing podinfo application

Now that you have a feel for how to navigate the dashboard. Let's deploy a new application and explore that as well. In this section we will use the [podinfo](https://github.com/stefanprodan/podinfo) sample web application.

### Deploying podinfo

1. Clone or navigate back to your git repository where you have bootstrapped Flux, for example:

```
git clone https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra
```

1. Create a `GitRepository` Source for podinfo

```
flux create source git podinfo \
--url=https://github.com/stefanprodan/podinfo \
--branch=master \
--interval=30s \
--export > ./clusters/my-cluster/podinfo-source.yaml
```

1. Commit and push the `podinfo-source` to the `fleet-infra` repository

```
git add -A && git commit -m "Add podinfo source"
git push
```

1. Create a `kustomization` to build and apply the podinfo manifest

```
flux create kustomization podinfo \
--target-namespace=flux-system \
--source=podinfo \
--path="./kustomize" \
--prune=true \
--interval=5m \
--export > ./clusters/my-cluster/podinfo-kustomization.yaml
```

1. Commit and push the `podinfo-kustomization` to the `fleet-infra` repository

```
git add -A && git commit -m "Add podinfo kustomization"
git push
```

### View the application in Weave GitOps

Flux will detect the updated `fleet-infra` and add podinfo. If we navigate back to the [dashboard](http://localhost:9001/) you should see the podinfo application appear.

![Applications summary view showing Flux System, Weave GitOps and Podinfo](/img/dashboard-applications-with-podinfo.png)

Click on podinfo and you will see details about the deployment, including that there is 1 pod available.

![Applications details view for podinfo showing 1 pods](/img/dashboard-podinfo-details.png)

### Customize podinfo

To customize a deployment from a repository you don’t control, you can use Flux in-line patches. The following example shows how to use in-line patches to change the podinfo deployment.

1. Add the `patches` section as shown below to the field spec of your podinfo-kustomization.yaml file so it looks like this:

```yaml title="./clusters/my-cluster/podinfo-kustomization.yaml"
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 60m0s
path: ./kustomize
prune: true
sourceRef:
kind: GitRepository
name: podinfo
targetNamespace: flux-system
// highlight-start
patches:
- patch: |-
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
name: podinfo
spec:
minReplicas: 3
target:
name: podinfo
kind: HorizontalPodAutoscaler
// highlight-end
```

1. Commit and push the podinfo-kustomization.yaml changes:

```
git add -A && git commit -m "Increase podinfo minimum replicas"
git push
```

3. Navigate back to the dashboard and you will now see 2 newly created pods

![Applications details view for podinfo showing 3 pods](/img/dashboard-podinfo-updated.png)


### Suspend updates

Suspending updates to a kustomization allows you to directly edit objects applied from a kustomization, without your changes being reverted by the state in Git.

To suspend updates for a kustomization, from the details page, click on the suspend button at the top, and you should see it be suspended:

![Podinfo details showing Podinfo suspended](/img/dashboard-podinfo-details-suspended.png)

This shows in the applications view with a yellow warning status indicating it is now suspended

![Applications summary view showing Podinfo suspended](/img/dashboard-podinfo-suspended.png)

To resume updates, go back to the details page, click the resume button, and after a few seconds reconsolidation will continue:

![Applications details view for podinfo being resumed](/img/dashboard-podinfo-updated.png)

## Complete!

Congratulations 🎉🎉🎉

You've now completed the getting started guide. We would welcome any and all [feedback](feedback-and-telemetry.md) on your experience.
2 changes: 1 addition & 1 deletion website/docs/gitops-run/get-started.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ gitops beta run ./podinfo --no-session --port-forward namespace=dev,resource=svc
```

You will now be asked if you want to install Flux and the GitOps
[dashboard](../getting-started.mdx). Answer yes and set a password, and
[dashboard](../getting-started/intro.mdx). Answer yes and set a password, and
shortly after you should be able to [open the dashboard](http://localhost:9001)
to see what's in your cluster - including the resources that GitOps
Run is operating.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/guides/displaying-custom-metadata.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ system or another external system, or documentation and comments that
are visible straight in the main UI.

We will use the podinfo application that we installed in the [getting
started guide](../getting-started.mdx) as an example. Open up the
started guide](../getting-started/intro.mdx) as an example. Open up the
podinfo kustomization and add annotations to it so it looks like this:

```yaml title="./clusters/my-cluster/podinfo-kustomization.yaml"
Expand Down
Loading

0 comments on commit 6e80bf4

Please sign in to comment.