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.

Sign up for GitHub

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

docs: update kargo quickstart guide #2521

Merged
merged 10 commits into from
Oct 24, 2024
Merged

docs: update kargo quickstart guide #2521

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
fd8a954
add: ui snapshots for quickstart guide
fykaa Sep 11, 2024
1b9b309
minor changes
fykaa Sep 12, 2024
101fe96
detailed instructions
fykaa Sep 12, 2024
0d1d0e4
stylistic navigation
fykaa Sep 27, 2024
03bf3ec
divide hacking on kargo cli into 2 sections: CLI+UI
fykaa Oct 23, 2024
67c37b8
Promote-to-test: update doc and graphics
fykaa Oct 23, 2024
9394b93
Merge remote-tracking branch 'upstream/main' into improve-docs-quicks…
fykaa Oct 23, 2024
a643464
refactor&& addressed reviews
fykaa Oct 24, 2024
fe7a25a
create resource using kubectl
fykaa Oct 24, 2024
fd27eb6
minor formatting fixes and minor wording changes
krancour Oct 24, 2024
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
321 changes: 36 additions & 285 deletions docs/docs/20-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,13 +261,15 @@ all three Argo CD `Application`s have not yet synced because they're not
configured to do so automatically, and in fact, the branches referenced by their
`targetRevision` fields do not even exist yet.

![Argo-dashboard-screenshot](../static/img/argo-dashboard.png)

:::info
Our three stages all existing in a single cluster is for the sake of expediency.
A single Argo CD control plane can manage multiple clusters, so these could just
as easily have been spread across multiple clusters.
:::

### Hands on with the Kargo CLI
### Define Your First Pipeline
fykaa marked this conversation as resolved.
Show resolved Hide resolved

Up to this point, we haven't done anything with Kargo -- in fact everything
we've done thus far should be familiar to anyone who's already using Argo CD and
Expand Down Expand Up @@ -508,52 +510,28 @@ the previous section.
EOF
```

:::info
Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints.
:::

1. Use the CLI to view our `Warehouse` resource:

```shell
kargo get warehouses --project kargo-demo
```
:::info
Kargo uses [semver](https://github.com/masterminds/semver#checking-version-constraints) to handle semantic versioning constraints.
:::
fykaa marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

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

Let's ditch this. I put this here, but it feels out of place now.

We can move this to be inline in the Go/CRD docs. (You can make a separate issue for that.)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

#2833


Sample output:
1. After applying the above configuration, you can view the pipeline you just created using the [Kargo Dashboard](https://localhost:31444/).
krancour marked this conversation as resolved.
Show resolved Hide resolved

```shell
NAME SHARD AGE
kargo-demo 13s
```
1. Choose your `Project`, <Hlt>kargo-demo</Hlt>, from the list of available `Project`s
1. You can find the pipeline you've created in the center of your Project screen.
1. The pipeline consists of connected rectangles representing:
1. <Hlt>Subscription</Hlt>: Has information about the container image repository that the `Warehouse` is subscribed to.
1. <Hlt>kargo-kemo</Hlt>: This represents your `Warehouse`. It will automatically subscribe to the image and should produce `Freight` shortly.
1. <Hlt>test</Hlt>, <Hlt>uat</Hlt>, and <Hlt>prod</Hlt>: These are the deployment `Stage` resources.
krancour marked this conversation as resolved.
Show resolved Hide resolved

1. Use the CLI to view our three `Stage` resources:

```shell
kargo get stages --project kargo-demo
```

Sample output:

```shell
NAME SHARD CURRENT FREIGHT HEALTH PHASE AGE
prod 0/1 Fulfilled NotApplicable 19s
test 0/1 Fulfilled NotApplicable 19s
uat 0/1 Fulfilled NotApplicable 19s
```
![Kargo-dashboard-screenshot](../static/img/kargo-dashboard-projects.png)

1. After a few seconds, our `Warehouse`, which subscribes to the
`public.ecr.aws/nginx/nginx` container image, also should have already
produced `Freight`:
produced `Freight`. You can monitor the status of `Freight` in the various stages directly on the interface,
where it will appear under the respective stages (`test`, `uat`, `prod`).
krancour marked this conversation as resolved.
Show resolved Hide resolved

```shell
kargo get freight --project kargo-demo
```

Sample output:
The top of the screen displays a Freight Timeline. As your application progresses through the pipeline, the timeline will update to show you the current `Stage` of your `Freight`.
krancour marked this conversation as resolved.
Show resolved Hide resolved

```shell
NAME ALIAS ORIGIN AGE
b2ceb4f821be8b682861c579171874028e4275fd lanky-pika Warehouse/kargo-demo 42s
```
:::info
`Freight` is a set of references to one or more versioned artifacts, which
may include:
Expand All @@ -568,269 +546,42 @@ the previous section.
version of the `public.ecr.aws/nginx/nginx` container image.
:::

1. We'll use it later, so save the ID of the `Freight` to an environment
variable:

```shell
export FREIGHT_ALIAS=$(kargo get freight --project kargo-demo --output jsonpath={.alias})
```

1. Now, let's _promote_ the `Freight` into the `test` `Stage`:

```shell
kargo promote --project kargo-demo --freight-alias $FREIGHT_ALIAS --stage test
```

Sample output:

```shell
promotion.kargo.akuity.io/test.01j2wbtrym4r3tktv38qzteh5h.7a6e91f promotion created
```

Query for `Promotion` resources within our project to see one has been
created:
### Promote to Test
krancour marked this conversation as resolved.
Show resolved Hide resolved

```shell
kargo get promotions --project kargo-demo
```
1. To promote `Freight` to the `test` `Stage`, select the existing `Freight` from
the Freight Timeline above. Click the three dots, choose <Hlt>Promote</Hlt>,
and then select <Hlt>Promote</Hlt> that appeared on the `test` `Stage`.
krancour marked this conversation as resolved.
Show resolved Hide resolved

The promotion may briefly appear in a `Pending` state, but it will likely
transition to `Running`, or even `Succeeded` within moments, as shown below:
krancour marked this conversation as resolved.
Show resolved Hide resolved

Our `Promotion` may briefly appear to be in a `Pending` phase, but more than
likely, it will almost immediately be `Running`, or even `Succeeded`:
![Kargo-dashboard-screenshot](../static/img/kargo-dashboard-promotion.png)

```shell
NAME SHARD STAGE FREIGHT PHASE AGE
test.01j92m3mx7jn49rc5p62tmnsf1.b2ceb4f test b2ceb4f821be8b682861c579171874028e4275fd Succeeded 57s
```
You'll notice a **_check mark_**, indicating a <Hlt>successful promotion</Hlt>.
krancour marked this conversation as resolved.
Show resolved Hide resolved
At this point, we can view all `Stage` resources in our `Project` and quickly see
that the `test` `Stage` is now either in a `Progressing` or `Healthy` state.

Once the `Promotion` has succeeded, we can again view all `Stage` resources
in our project, and at a glance, see that the `test` `Stage` is now either
in a `Progressing` or `Healthy` state.
Once the `test` `Stage` reaches a `Healthy` state, you can further confirm the
success of this process by visiting the test instance of the site at [localhost:30081](http://localhost:30081).

```shell
kargo get stages --project kargo-demo
```
By checking the detailed `status` of the `test` `Stage`, you'll see it now reflects
the current `Freight` and may include a history of all the previous `Freight` that
passed through this `Stage`, listed from the most recent to the oldest.

Sample output:

```shell
NAME SHARD CURRENT FREIGHT HEALTH PHASE AGE
prod 0/1 Fulfilled NotApplicable 1m34s
test b2ceb4f821be8b682861c579171874028e4275fd Healthy Steady 1m34s
uat 0/1 Fulfilled NotApplicable 1m34s
```

We can repeat the command above until our `test` `Stage` is in a `Healthy`
state and we can further validate the success of this entire process by
visiting the test instance of our site at
[localhost:30081](http://localhost:30081).

If we once again view the `status` of our `test` `Stage` in more detail, we
will see that it now reflects its current `Freight`, and the history of all
`Freight` that have passed through this stage. (The collection is ordered
most to least recent.)

```shell
kargo get stage test --project kargo-demo --output jsonpath-as-json={.status}
```

Sample output:

```shell
[
{
"freightHistory": [
{
"id": "b69280b76a5f5dc40f9dbb1357f553a22958dda1",
"items": {
"Warehouse/kargo-demo": {
"images": [
{
"digest": "sha256:880533409097c86a27961c44bfcd60ca478a693e6baa4d9ee3c09b45865e5ea6",
"repoURL": "public.ecr.aws/nginx/nginx",
"tag": "1.27.1"
}
],
"name": "b2ceb4f821be8b682861c579171874028e4275fd",
"origin": {
"kind": "Warehouse",
"name": "kargo-demo"
}
}
}
}
],
"freightSummary": "b2ceb4f821be8b682861c579171874028e4275fd",
"health": {
"output": [
{
"applicationStatuses": [
{
"Name": "kargo-demo-test",
"Namespace": "argocd",
"health": {
"status": "Healthy"
},
"operationState": {
"finishedAt": "2024-09-30T23:26:40Z",
"message": "successfully synced (all tasks run)",
"operation": {
"info": [
{
"name": "Reason",
"value": "Promotion triggered a sync of this Application resource."
},
{
"name": "kargo.akuity.io/freight-collection",
"value": "b69280b76a5f5dc40f9dbb1357f553a22958dda1"
}
],
"initiatedBy": {
"automated": true,
"username": "kargo-controller"
},
"retry": {},
"sync": {
"revisions": [
"stage/test"
],
"syncOptions": [
"CreateNamespace=true"
]
}
},
"phase": "Succeeded",
"syncResult": {
"revision": "707412fa2be1aae72767c0acb652684c233a2802",
"source": {
"repoURL": "https://github.com/krancour/kargo-demo-gitops-2.git",
"targetRevision": "stage/test"
}
}
},
"sync": {
"revision": "707412fa2be1aae72767c0acb652684c233a2802",
"status": "Synced"
}
}
]
}
],
"status": "Healthy"
},
"lastHandledRefresh": "2024-09-30T23:31:40Z",
"lastPromotion": {
"finishedAt": "2024-09-30T23:31:37Z",
"freight": {
"images": [
{
"digest": "sha256:880533409097c86a27961c44bfcd60ca478a693e6baa4d9ee3c09b45865e5ea6",
"repoURL": "public.ecr.aws/nginx/nginx",
"tag": "1.27.1"
}
],
"name": "b2ceb4f821be8b682861c579171874028e4275fd",
"origin": {
"kind": "Warehouse",
"name": "kargo-demo"
}
},
"name": "test.01j92m3mx7jn49rc5p62tmnsf1.b2ceb4f",
"status": {
"finishedAt": "2024-09-30T23:31:37Z",
"freight": {
"images": [
{
"digest": "sha256:880533409097c86a27961c44bfcd60ca478a693e6baa4d9ee3c09b45865e5ea6",
"repoURL": "public.ecr.aws/nginx/nginx",
"tag": "1.27.1"
}
],
"name": "b2ceb4f821be8b682861c579171874028e4275fd",
"origin": {
"kind": "Warehouse",
"name": "kargo-demo"
}
},
"freightCollection": {
"id": "b69280b76a5f5dc40f9dbb1357f553a22958dda1",
"items": {
"Warehouse/kargo-demo": {
"images": [
{
"digest": "sha256:880533409097c86a27961c44bfcd60ca478a693e6baa4d9ee3c09b45865e5ea6",
"repoURL": "public.ecr.aws/nginx/nginx",
"tag": "1.27.1"
}
],
"name": "b2ceb4f821be8b682861c579171874028e4275fd",
"origin": {
"kind": "Warehouse",
"name": "kargo-demo"
}
}
}
},
"healthChecks": [
{
"config": {
"apps": [
{
"desiredRevisions": [
"707412fa2be1aae72767c0acb652684c233a2802"
],
"name": "kargo-demo-test",
"namespace": "argocd"
}
]
},
"uses": "argocd-update"
}
],
"phase": "Succeeded",
"state": {
"commit": {
"commit": "707412fa2be1aae72767c0acb652684c233a2802"
},
"update-image": {
"commitMessage": "Updated ./src/base to use new image\n\n- public.ecr.aws/nginx/nginx:1.27.1"
}
}
}
},
"observedGeneration": 1,
"phase": "Steady"
}
]
```

1. If we look at our `Freight` in greater detail, we'll see that by virtue of
1. If we select the `Freight` from the <Hlt>Freight Timeline</Hlt>, we'll see that by virtue of
the `test` `Stage` having achieved a `Healthy` state, the `Freight` is now
_verified_ in `test`, which designates it as eligible for promotion to the
next `Stage` -- in our case, `uat`.

![Kargo-Freight-Verified](../static/img/kargo-freight-verified.png)

:::note
Although this example does not demonstrate it, it is also possible to verify
the `Freight` in a `Stage` using user-defined processes. See the
[relevant section](./15-concepts.md#verifications) of the concepts page to
learn more.
:::

```shell
kargo get freight --alias $FREIGHT_ALIAS --project kargo-demo --output jsonpath-as-json={.status}
```

Sample output:

```shell
[
{
"verifiedIn": {
"test": {}
}
}
]
```

### Behind the Scenes

So what has Kargo done behind the scenes?
Expand Down
Binary file added docs/static/img/argo-dashboard.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/kargo-dashboard-projects.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/kargo-dashboard-promotion.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/kargo-freight-verified.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.