Skip to content

Commit

Permalink
Improve Docs (#437)
Browse files Browse the repository at this point in the history 
* Scale down small images, put tables under headings

* use scalable images for small images, and a png for clarity on supply chain

* Improve docs

- Restructure reference
- rewrite urls when switching versions inside the reference/ docs
- use coninstant column hard wraps in docs
- fixed all broken links

[closes #427]

Co-authored-by: Emily Johnson <emjohnson@vmware.com>

* Rearrange Refs for workload/deliverable

Co-authored-by: Emily Johnson <emjohnson@vmware.com>
  • Loading branch information
@squeedee @emmjohnson
squeedee and emmjohnson authored Dec 8, 2021
1 parent 1465169 commit e875402
Show file tree
Hide file tree
Showing 20 changed files with 2,249 additions and 888 deletions.
58 changes: 32 additions & 26 deletions site/content/docs/development/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,42 +6,48 @@ cascade:

## TLDR

Cartographer is a [Supply Chain Choreographer](https://tanzu.vmware.com/developer/guides/ci-cd/supply-chain-choreography/) for Kubernetes. It allows App Operators to create pre-approved paths to production by integrating Kubernetes resources with the elements of their existing toolchains (e.g. Jenkins).
Cartographer is
a [Supply Chain Choreographer](https://tanzu.vmware.com/developer/guides/ci-cd/supply-chain-choreography/) for
Kubernetes. It allows App Operators to create pre-approved paths to production by integrating Kubernetes resources with
the elements of their existing toolchains (e.g. Jenkins).

**Each** pre-approved supply chain creates a paved road to production; orchestrating supply chain resources - test, build, scan, and deploy - allowing developers to be able to focus on delivering value to their users while also providing App Operators with the peace of mind that all code in production has passed through all of the steps of an approved workflow.
**Each** pre-approved supply chain creates a paved road to production; orchestrating supply chain resources - test,
build, scan, and deploy - allowing developers to be able to focus on delivering value to their users while also
providing App Operators with the peace of mind that all code in production has passed through all of the steps of an
approved workflow.

## Cartographer Design and Philosophy

Cartographer allows users to define all of the steps that an application must go through to create an image and Kubernetes configuration.
Users achieve this with the Supply Chain abstraction ([Spec Reference](reference.md#clustersupplychain)).
Cartographer allows users to define all of the steps that an application must go through to create an image and
Kubernetes configuration. Users achieve this with the Supply Chain
abstraction ([Spec Reference](reference/workload#clustersupplychain)).

The supply chain consists of resources that are specified via Templates.
Each template acts as a wrapper for existing Kubernetes resources and allows them to be used with Cartographer.
There are currently four different types of templates that can be use in a Cartographer supply chain:
The supply chain consists of resources that are specified via Templates. Each template acts as a wrapper for existing
Kubernetes resources and allows them to be used with Cartographer. There are currently four different types of templates
that can be use in a Cartographer supply chain:

* Source Template ([Spec Reference](reference.md#clustersourcetemplate))
* Image Template ([Spec Reference](reference.md#clusterimagetemplate))
* Config Template ([Spec Reference](reference.md#clusterconfigtemplate))
* Generic Template ([Spec Reference](reference.md#clustertemplate))
* Source Template ([Spec Reference](reference/template#clustersourcetemplate))
* Image Template ([Spec Reference](reference/template#clusterimagetemplate))
* Config Template ([Spec Reference](reference/template#clusterconfigtemplate))
* Generic Template ([Spec Reference](reference/template#clustertemplate))

Contrary to many other Kubernetes native workflow tools that already exist in the market,
Cartographer does not “run” any of the objects themselves. Instead, it monitors the execution of
each resource and templates the following resource in the supply chain after a given resource has
completed execution and updated its status.
Contrary to many other Kubernetes native workflow tools that already exist in the market, Cartographer does not “run”
any of the objects themselves. Instead, it monitors the execution of each resource and templates the following resource
in the supply chain after a given resource has completed execution and updated its status.

The supply chain may also be extended to include integrations to existing CI/CD pipelines by using the Runnable CRD
(which is part of Cartographer). The Runnable CRD acts as a wrapper for CRDs that are immutable (meaning that instead
of updating an object, a new object would be created). There are a number of CI/CD CRDs that follow this pattern,
including Tekton. The Runnable CRD provides a declarative way for pipelines to be run inside of Cartographer.
The supply chain may also be extended to include integrations to existing CI/CD pipelines by using the Runnable CRD
(which is part of Cartographer). The Runnable CRD acts as a wrapper for CRDs that are immutable (meaning that instead of
updating an object, a new object would be created). There are a number of CI/CD CRDs that follow this pattern, including
Tekton. The Runnable CRD provides a declarative way for pipelines to be run inside of Cartographer.

While the supply chain is operator facing, Cartographer also provides an abstraction for developers called workloads
([Spec Reference](reference.md#workload)). Workloads allow developers to create application specifications such as the
location of their repository, environment variables and service claims.
While the supply chain is operator facing, Cartographer also provides an abstraction for developers called workloads
([Spec Reference](reference/workload#workload)). Workloads allow developers to create application specifications such as
the location of their repository, environment variables and service claims.

By design, supply chains can be reused by many workloads. This allows an operator to specify the steps in the path to
production a single time, and for developers to specify their applications independently but for each to use the same
path to production. The intent is that developers are able to focus on providing value for their users and can reach
production quickly and easily, while providing peace of mind for app operators, who are ensured that each application
By design, supply chains can be reused by many workloads. This allows an operator to specify the steps in the path to
production a single time, and for developers to specify their applications independently but for each to use the same
path to production. The intent is that developers are able to focus on providing value for their users and can reach
production quickly and easily, while providing peace of mind for app operators, who are ensured that each application
has passed through the steps of the path to production that they’ve defined.

![Cartographer High Level Diagram](img/ownership-flow.png)
43 changes: 21 additions & 22 deletions site/content/docs/development/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ Two kinds of blueprint work together to provide **code-to-production**, [Supply

| Blueprint | Owner | Valid Templates |
| ----------- | ----------- | ----------- |
| [ClusterSupplyChain](reference/#clustersupplychain) | [Workload](reference/#workload) | [ClusterSourceTemplate](reference/#clustersourcetemplate), [ClusterImageTemplate](reference/#clusterimagetemplate), [ClusterConfigTemplate](reference/#clusterconfigtemplate), [ClusterTemplate](reference/#clustertemplate) |
| [ClusterDelivery](reference/#delivery) | [Deliverable](reference/#deliverable) | [ClusterSourceTemplate](reference/#clustersourcetemplate), [ClusterDeploymentTemplate](reference/#clusterdeploymenttemplate), [ClusterTemplate](reference/#clustertemplate) |
| [ClusterSupplyChain](reference/workload#clustersupplychain) | [Workload](reference/workload#workload) | [ClusterSourceTemplate](reference/template#clustersourcetemplate), [ClusterImageTemplate](reference/template#clusterimagetemplate), [ClusterConfigTemplate](reference/template#clusterconfigtemplate), [ClusterTemplate](reference/template#clustertemplate) |
| [ClusterDelivery](reference/deliverable#clusterdelivery) | [Deliverable](reference/deliverable#deliverable) | [ClusterSourceTemplate](reference/template#clustersourcetemplate), [ClusterDeploymentTemplate](reference/template#clusterdeploymenttemplate), [ClusterTemplate](reference/template#clustertemplate) |

Blueprints are a list of templates (called resources) that defines how the templates depend upon each other. It forms
the dependency graph of your supply chain or delivery.
Expand All @@ -30,11 +30,19 @@ Blueprints consist of:
* **Parameters** to pass to the template
* **Inputs**, which specify dependencies for the template

![Blueprint](../img/blueprint.jpg)
{{< figure src="../img/blueprint.svg" alt="Blueprint" width="400px" >}}
<!-- https://miro.com/app/board/uXjVOeb8u5o=/ -->

### Templates

| Output | Template |
| ----------- | ----------- |
| Config | [ClusterConfigTemplate](reference/template#clusterconfigtemplate) |
| Image | [ClusterImageTemplate](reference/template#clusterimagetemplate) |
| Source | [ClusterSourceTemplate](reference/template#clustersourcetemplate) |
| Deployment | [ClusterDeploymentTemplate](reference/template#clusterdeploymenttemplate) |
| | [ClusterTemplate](reference/template#clustertemplate) |

Templates create or update resources (i.e. kubectl apply).

Templates consist of:
Expand All @@ -43,21 +51,17 @@ Templates consist of:
* **Output paths** which tell Cartographer where to find the output of the Kubernetes resource
* The path field depends upon the specific template kind.

![Template](../img/template.jpg)

Templates are typed by the output they produce.
Templates are typed by the output their underlying resource produces.

| Output | Template |
| ----------- | ----------- |
| Config | [ClusterConfigTemplate](reference/#clusterconfigtemplate) |
| Image | [ClusterImageTemplate](reference/#clusterimagetemplate) |
| Source | [ClusterSourceTemplate](reference/#clustersourcetemplate) |
| Deployment | [ClusterDeploymentTemplate](reference/#clusterdeploymenttemplate) |
| | [ClusterTemplate](reference/#clustertemplate) |
{{< figure src="../img/template.svg" alt="Template" width="400px" >}}

### Owners
| Owner | Blueprint |
| ----------- | ----------- |
| Workload | ClusterSupplyChain |
| Deliverable | ClusterDelivery |

Owners represent the workload or deliverable, which in many cases refer to a single application's source or image
Owners represent the **workload** or **deliverable**, which in many cases refer to a single application's source or image
location.

Owners are the developer provided configuration which cause a blueprint to be reconciled into resources.
Expand All @@ -68,14 +72,9 @@ They consist of:
* **Labels**: blueprints will select based on the labels of an owner, see [selectors](#selectors)
* **Params**: parameters supplied to the blueprint, see [Parameter Hierarchy](#parameter-hierarchy)
* **Source**: The source reference for the input to the Supply Chain or Delivery Blueprints,
see [Workload](reference.md/#workload) and [Deliverable](reference.md/#deliverable)
see [Workload](reference/workload#workload) and [Deliverable](reference/deliverable#deliverable)

![Owner](../img/owner.jpg)

| Owner | Blueprint |
| ----------- | ----------- |
| Workload | ClusterSupplyChain |
| Deliverable | ClusterDelivery |
{{< figure src="../img/owner.svg" alt="Owner" width="400px" >}}

## Theory of operation

Expand Down Expand Up @@ -111,7 +110,7 @@ When Cartographer reconciles an owner, each resource in the matching blueprint i
### ClusterSupplyChain
A ClusterSupplyChain blueprint continuously integrates and builds your app.

![ClusterSupplyChain](../img/supplychain.jpg)
![ClusterSupplyChain](../img/supplychain.png)

### ClusterDelivery
A ClusterDelivery blueprint continuously deploys and validates Kubernetes configuration to a cluster.
Expand Down
Binary file removed site/content/docs/development/img/blueprint.jpg
View file
Binary file not shown.
Loading

0 comments on commit e875402

Please sign in to comment.