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

Merge concepts and design into single document #374

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open
75 changes: 60 additions & 15 deletions docs/concepts.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
# Concepts

## Understanding the Fundamentals

It is important to understand the fundamentals of the underlying technology that Arlon is built on, before you start making use of Arlon.
We recommend a good understanding of core concepts around [Docker](https://www.docker.com/), containerization, [Kubernetes](https://kubernetes.io/), GitOps and Continuous Delivery to understand the fundamentals behind Arlon.
We also recommend having a basic understanding of application templating technologies such as [Helm](https://helm.sh) and [Kustomize](https://kustomize.io) that are commonly used with Kubernetes.

## Management cluster

This Kubernetes cluster hosts the following components:
Before you can use arlon, you need a Kubernetes cluster to host the following components:

- ArgoCD
- Arlon
- Cluster management stacks e.g. Cluster API and/or Crossplane

The Arlon state and controllers reside in the arlon namespace.
The Arlon state and controllers reside in the arlon namespace on this cluster.

## Configuration bundle

Expand All @@ -17,6 +23,15 @@ produce a set of Kubernetes manifests via a *tool*. This closely follows ArgoCD'
definition of *tool types*. Consequently, the list of supported bundle
types mirrors ArgoCD's supported set of manifest-producing tools.
Each bundle is defined using a Kubernetes ConfigMap resource in the arlon namespace.
Additionally, a bundle can embed the data itself ("static bundle"), or contain a reference
to the data ("dynamic bundle"). A reference can be a URL, GitHub location, or Helm repo location.
The current list of supported bundle types is:

- manifest_inline: a single manifest yaml file embedded in the resource
- manifest_ref: a reference to a single manifest yaml file
- dir_inline: an embedded tarball that expands to a directory of YAML files
- helm_inline: an embedded Helm chart package
- helm_ref: an external reference to a Helm chart

### Static bundle

Expand All @@ -41,6 +56,18 @@ by ArgoCD, including plain YAML, Helm and Kustomize.
When the user updates a dynamic bundle in git, all clusters consuming that bundle
(through a profile specified at cluster creation time) will acquire the change.

### Bundle purpose

Bundles can specify an optional *purpose* to help classify and organize them.
In the future, Arlon may order bundle installation by purpose order (for e.g.
install bundles with purpose=*networking* before others) but that is not the
case today. The currently *suggested* purpose values are:

- networking
- add-on
- data-service
- application

### Other properties

A bundle can also have a comma-separated list of tags, and a description.
Expand All @@ -51,6 +78,15 @@ Tags can be useful for classifying bundles, for e.g. by type

A profile expresses a desired configuration for a Kubernetes cluster.
It is just a set of references to bundles (static, dynamic, or a combination).
A profile is composed of:

- An optional clusterspec. If specified, it allows the profile
to be used to create new clusters.
If absent, the profile can only be applied to existing clusters.
- A list of bundles specifying the configuration to apply onto the cluster
once it is operational
- An optional list of `values.yaml` settings for any Helm Chart type bundle
in the bundle list
A profile can be static or dynamic.

### Static profile
Expand Down Expand Up @@ -81,24 +117,33 @@ or acquire new bundles in real time.

## Cluster

An Arlon cluster, also known as workload cluster, is a Kubernetes cluster
An Arlon cluster, also called a 'workload cluster', is a Kubernetes cluster
that Arlon creates and manages via a git directory structure stored in
the workspace repository.

(Under construction)

## Cluster spec
## Cluster Specification

A cluster spec contains desired settings when creating a new cluster.
The Cluster Specification, also called the 'Base Cluster' contains the desired settings when creating a new cluster.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Cluster Spec and Base Cluster are not identical, even if they have similarities. Why merge the concepts here? And why do all of this if this is going to be replaced by Cluster Templates?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

okay I fixed it to keep both in the concepts document. please take another look

They currently include:

- API Provider: the cluster orchestration technology. Supported values are `CAPI` (Cluster API) and `xplane` (Crossplane)
- Cloud Provider: the infrastructure cloud provider. The currently supported values is `aws`, with `gcp` and `azure` support coming later.
- Type: the cluster type. Some API providers support more than one type. On `aws` cloud, Cluster API supports `kubeadm` and `eks`, whereas Crossplane only supports `eks`.
- The (worker) node instance type
- The initial (worker) node count
- The Kubernetes version
- A predefined list of Cluster API objects: Cluster, Machines, Machine Deployments, etc. to be deployed in the current namespace
- The specific infrastructure provider to be used (e.g aws)
- Kubernetes version
- Cluster nodepool type that need to be used for creating the cluster manifest (e.g eks, eks-managedmachinepool)

To know more about 'Base Cluster', read about it [here](./baseclusters.md)

## Cluster Chart
Copy link
Collaborator

Choose a reason for hiding this comment

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

The cluster chart is only used by gen1 clusters. Gen2 clusters created from base clusters don't use the cluster chart. It's confusing to describe both base clusters and cluster charts in the same document.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

okay then I will remove the cluster chart stuff from the 0.10 docs version, once I am able to see it on the doc site


The cluster chart is a Helm chart that creates (and optionally applies) the manifests necessary to create a cluster and deploy desired configurations and applications to it as a part of cluster creation, the following resources are created: The profile's Cluster Specification, bundle list and other settings are used to generate values for the cluster chart, and the chart is deployed as a Helm release into the *arlon* namespace in the management cluster.

## Base cluster
Here is a summary of the kinds of resources generated and deployed by the chart:

To know more about basecluster (Arlon gen2 clusters), read it [here](./baseclusters.md)
- A unique namespace with a name based on the cluster's name. All subsequent
resources below are created inside that namespace.
- The stack-specific resources to create the cluster (for e.g. Cluster API resources)
- A ClusterRegistration to automatically register the cluster with ArgoCD
- A GitRepoDir to automatically create a git repo and/or directory to host a copy
of the expanded bundles. Every bundle referenced by the profile is
copied/unpacked into its own subdirectory.
- One ArgoCD Application resource for each bundle.