Skip to content

Commit 4fc9ecd

Browse files
lotharbachlotharbach
committed
Add documentation for 1.112
1 parent 293ec5e commit 4fc9ecd

21 files changed

+2730
-1979
lines changed

‎docs/release-notes/next.md

-1,979
Large diffs are not rendered by default.

‎docs/release-notes/v1.112.md

+1,989
Large diffs are not rendered by default.

‎docs/versioned_docs/version-1.112.x/architecture-configuration/_category_.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Architecture / Configuration",
3+
"position": 2,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Architecture description of the YAKE Gardener distribution"
7+
}
8+
}

‎docs/versioned_docs/version-1.112.x/architecture-configuration/architecture.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Architecture
6+
7+
## High Level Overview
8+
![YAKE High Level Overview](high-level-overview.excalidraw.png "YAKE High Level Overview")
9+
10+
Let's start off with the very high level overview in the block diagram above. The most important aspect to note is that all deployments needed for the [Gardener](https://gardener.cloud/) installation are based on helm charts. Since the helm charts developed in the Gardener upstream are distributed over several repositories in the Gardener [Github organization](https://github.com/gardener/external-dns-management), we consolidated the relevant charts in another [repository](https://github.com/gardener-community/gardener-charts) hosted on Github. Consequently, YAKE fetches helm charts from several helm repositories and deploys the components for the Gardener installation into the base cluster.
11+
12+
## Detailed Architecture
13+
14+
A more detailed view of the YAKE architecture is depicted in the block diagram below.
15+
16+
![YAKE architecture](yake-architecture.png "YAKE architecture")
17+
18+
### Main entry points
19+
20+
Conceptually, there are two entry points for Gardener operators to interact with the configuration:
21+
22+
1. The `yake-config` secret in the base cluster
23+
2. The YAKE configuration git repository
24+
25+
The reason for having a dedicated `yake-config` secret lies in the assumption that an operator does not want to store credentials such as dnsprovider credentials in a git repository. Of course, this could also be handled by solutions like [sops](https://github.com/mozilla/sops), but we wanted to let the operator decide where to store the `yake-config` secret in the end.
26+
27+
### General Concepts
28+
29+
As observed from the figure, the YAKE concept divides the installation process into tree separate stages: The `configuration`, `pre-gardener` stage and the `gardener` stage. The configuration stages transfer the content of the `yake-config` secret into separate secrets serving as values for the eventually deployed helm charts. Consequently, the default values given in the upstream values files for the helm charts are extended by the `*-base-values` secrets, so that all components come with a meaningful base configuration. This base configuration is assumed to be homogeneous across many Gardener environments. For the parts which are environment specific, another set of secrets stores another set of values for the helm charts. These secrets are pulled in from the YAKE configuration git repository and managed by a GitOps workflow.
30+
31+
As we assume that the underlying base cluster does not come with any services installed, the `pre-gardener` stage ensures that the required services are deployed to the cluster. In more detail, the following services and resources are deployed:
32+
33+
- [cert-manager](https://cert-manager.io/) for internal certificate handling
34+
- [cert-management](https://github.com/gardener/cert-management) for browser trusted certificate handling
35+
- An `issuer` resource representing a certificate issuer in the base cluster
36+
- [external-dns-management](https://github.com/gardener/external-dns-management) for creation of DNS entries
37+
- A `dnsprovider` resource representing a DNS provider such as azure-dns, aws-route53 etc. in the base cluster
38+
- [ingress-nginx](https://kubernetes.github.io/ingress-nginx/) as ingress controller
39+
40+
In the `gardener` stage, the gardener specific components are deployed to the base cluster and to the [virtual garden](https://github.com/gardener/garden-setup#concept-the-virtual-cluster). The most important aspect to note here is that the [gardenlet](https://gardener.cloud/docs/gardener/concepts/gardenlet/) is deployed to the base cluster, i.e. the base cluster also serves as initial seed cluster for the resulting Gardener environment.
41+
42+
43+
44+
### backups
45+
46+
### webterminal

‎docs/versioned_docs/version-1.112.x/architecture-configuration/extensions-config.md

+110
Large diffs are not rendered by default.

‎docs/versioned_docs/version-1.112.x/architecture-configuration/helm-flux.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Working with Helm and Flux
6+
7+
On this page, you'll find some useful information on how to work with the commandline interfaces for [helm](https://helm.sh/) and [flux](https://fluxcd.io/) in the context of your YAKE-based Gardener installation.
8+
9+
## Useful Helm Commands
10+
11+
First things first. As already introduced in the [architecture description](./architecture.md), most of the YAKE helm charts stem from a helm repository hosted at `gardener.community.github.io/gardener-charts`. Consider adding this helm repository to your local repository cache by
12+
13+
```sh
14+
helm repo add gardener-charts https://gardener-community.github.io/gardener-charts
15+
helm repo update
16+
```
17+
18+
Afterwards you can use get further information about the charts using the helm cli.
19+
20+
### Show upstream chart info
21+
22+
E.g., for the `cloudprofiles` chart:
23+
24+
```sh
25+
helm show chart gardener-charts/cloudprofiles
26+
```
27+
28+
### Show upstream helm default values
29+
30+
E.g., for the `cloudprofiles` chart:
31+
32+
```sh
33+
helm show values gardener-charts/cloudprofiles
34+
```
35+
36+
## Useful Flux Commands
37+
38+
### Check flux versions
39+
40+
The flux controllers running in the basecluster are maintained by YAKE itself, i.e. the flux controllers will be updated with YAKE updates. You can check the state of your cli version and the version of the cluster side components by
41+
42+
```sh
43+
flux version
44+
```
45+
46+
If you feel like your cli version is outdated. Go ahead and download a recent version from [the Github release page](https://github.com/fluxcd/flux2/releases). If you feel like your in-cluster components are outdated, think about updating YAKE.
47+
48+
### Reconcile of a resource
49+
50+
If you want to get fast feedback in your GitOps workflow you can trigger the reconciliation of resources manually using the `flux reconcile command`. If you want a `helmrelease` to be reconciled immediately, you can achieve this by the following command:
51+
52+
```sh
53+
flux reconcile helmrelease <NAME_OF_HELMRELEASE>
54+
```
55+
56+
### Suspend/Resume Reconciliation of a resource
57+
58+
Maybe you want to get your hands dirty and do some manual (i.e. not GitOps driven) configuration changes. For instance, this could be useful in staging environments for rapid prototyping. In this case, you need to make sure that flux does not revert your "dirty" changes and suspend the reconciliation of the affected resources. Checkout the help for `flux suspend` to get further information
59+
60+
```sh
61+
flux suspend -h
62+
```
63+
64+
E.g., a helmrelease can be suspended by
65+
66+
```sh
67+
flux suspend helmrelease <NAME_OF_HELMRELEASE>
68+
```
69+
70+
Don't forget to resume the reconciliation, when you are done with your experiments so that flux will take over the control of your deployed resources again:
71+
72+
```sh
73+
flux resume helmrelease <NAME_OF_HELMRELEASE>
74+
```
75+
76+
:::note
77+
Sometimes you will need to `suspend` and `resume` resources in order to trigger an update of the deployed resources. If have the impression that the state in the cluster does not match your definitions in the git repository, try to `suspend` and `resume` the corresponding resources, wait for reconciliation, and see that the state matches the git repository again.
78+
:::

‎docs/versioned_docs/version-1.112.x/architecture-configuration/high-level-overview.excalidraw.png

43.4 KB
Loading

‎docs/versioned_docs/version-1.112.x/architecture-configuration/yake-architecture.png

847 KB
Loading

‎docs/versioned_docs/version-1.112.x/architecture-configuration/yake-config-gitrepo.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# The YAKE config git repository
6+
As already introduced in the [architecture diagram](./architecture.md), values for the helm charts deployed for the Gardener installation are configured and maintained in a GitOps workflow. For instance, your repository tree looks like this:
7+
```
8+
.
9+
├── config
10+
│   ├── cloudprofiles-values.yaml
11+
│   ├── dashboard-values.yaml
12+
│   ├── extensions-values.yaml
13+
│   ├── gardener-values.yaml
14+
│   ├── gardenlet-values.yaml
15+
│   ├── identity-values.yaml
16+
│   └── kustomization.yaml
17+
├── flux
18+
│   ├── yake-env-config.yaml
19+
│   └── yake-env-garden-content.yaml
20+
├── garden-content
21+
│   ├── admin-clusterrolebinding.yaml
22+
│   ├── kustomization.yaml
23+
│   ├── project-dev.yaml
24+
│   └── rbac.yaml
25+
└── kustomization.yaml
26+
```
27+
The top-level `kustomization.yaml` file contains [`Kustomization`](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/) pointing to the files in the `flux` directory. Inside the `flux` directory two flux `Kustomizations` [`Kustomization`](https://fluxcd.io/flux/components/kustomize/api/)s reside which point to the `config` directory and the `garden-content` directory.
28+
29+
:::caution
30+
The top-level `kustomization.yaml` is of type `kustomize.config.k8s.io/v1beta1`, whereas the `Kustomization`s in the `flux` directory are of type `kustomize.toolkit.fluxcd.io/v1beta2`. Therefore, you will only find the `Kustomization`s defined in the `flux` directory in your base cluster, when watching `Kustomization` resources.
31+
:::
32+
33+
### The `config` Directory
34+
In the `config` directory, you find configuration files defining values for the deployed helm charts. All files entail the same "header", and are constructed like in the following example for `cloudprofiles-values.yaml`
35+
```yaml
36+
apiVersion: v1
37+
kind: Secret
38+
metadata:
39+
name: cloudprofiles-values
40+
namespace: flux-system
41+
type: Opaque
42+
stringData:
43+
values.yaml: |
44+
```
45+
Below of the key `stringData.values.yaml` you can insert your configuration.
46+
47+
:::tip
48+
As the upstream helm charts are distributed over several repositories, there is no single documentation page for possible helm chart values. You can get information on the default values by e.g.
49+
```sh
50+
helm repo add gardener-charts https://gardener-community.github.io/gardener-charts
51+
helm repo update
52+
helm show values gardener-charts/<CHART_NAME>
53+
```
54+
:::
55+
56+
### The `garden-content` Directory
57+
In the `garden-content` Directory, resources to be deployed to the [virtual garden](https://github.com/gardener/garden-setup#concept-the-virtual-cluster) are defined. You can easily add some resources, if you need more than if the example from above does not fit your needs. For instance, you can create [`Project`](https://gardener.cloud/docs/gardener/api-reference/core/#core.gardener.cloud/v1beta1.Project)s or further [`Cloudprofile`](https://gardener.cloud/docs/gardener/api-reference/core/#core.gardener.cloud/v1beta1.CloudProfile)s here.
58+
:::note
59+
The `garden-content` folder also contains a `kustomization.yaml` file which just lists the resources to be deployed to the [virtual garden](https://github.com/gardener/garden-setup#concept-the-virtual-cluster). You can just comment our resources you do not want to deploy for a moment but still keep in you git repository for documentation purposes.
60+
:::

‎docs/versioned_docs/version-1.112.x/architecture-configuration/yake-config-secret.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# The YAKE config secret
6+
Via the `yake-config` secret, some basic parameters for the resulting Gardener installation are configured. In particular, values which should be kept secret such as dnsprovider credentials are set in `yake-config`.
7+
As the `yake-config` secret serves as input values for the `configuration` helm chart (see [architecture](./architecture.md)), the secret is defined as
8+
9+
```yaml
10+
apiVersion: v1
11+
kind: Secret
12+
metadata:
13+
name: yake-config
14+
namespace: flux-system
15+
type: Opaque
16+
stringData:
17+
values.yaml: |
18+
...
19+
```
20+
21+
and the configuration needs to be inserted below `stringData.values.yaml`. The configuration options are listed and explained below.
22+
23+
| Field | Subfield | Subfield | Description |
24+
| :----------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
25+
| `clusterIdentity` <br />string | | | a unique identifier for your garden cluster |
26+
| `dashboard` | | | |
27+
| | `clientSecret` <br />string | | client secret e.g. some value obtained by `openssl rand -hex 20` |
28+
| | `sessionSecret` <br />string | | session secret e.g. some value obtained by `openssl rand -hex 20` |
29+
| `kubeApiServer` | | | |
30+
| | `basicAuthPassword` <br />string | | basic auth password for kubeapiserver e.g. `openssl rand -hex 20` |
31+
| `issuer` | | | |
32+
| | `acme` | | |
33+
| | | `email` <br />string | Email address used for certificate handlin |
34+
| | | `server` <br />string | acme server, letsencryp production by default |
35+
| | `ca` | | ca of the acme server, not needed when using letsencrypt production |
36+
| `domains` | | | |
37+
| | `global` | | global means used for ingress, gardener defaultDomain and internalDomain |
38+
| | | `domain` <br />string | domain for your gardener installation, e.g. the dashboard will appear under dashboard.domain |
39+
| | | `provider` <br />string | DNS provider for your installation, e.g. azure-dns, aws-route53, openstack-designate etc. |
40+
| | | `credentials` <br />[dnscredentials](https://github.com/gardener/external-dns-management/tree/master/examples) | DNS provider credential, see [examples](https://github.com/gardener/external-dns-management/tree/master/examples) |
41+
| `registryOverwrite` | | | See Guide [Use different container registry](../guides/registryOverwrite.md) |

‎docs/versioned_docs/version-1.112.x/faq.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
sidebar_position: 5
3+
title: FAQ
4+
---
5+
6+
### Which Gardener version do I get with YAKE?
7+
8+
We keep the pace of the Gardener upstream and release new Gardener versions with YAKE as soon as possible. This enables YAKE users the keep their installation up-to-date, and get the experience of new features in a two week rhythm.
9+
10+
### Can I migrate from my garden-setup-based installation to YAKE?
11+
12+
Yes, this is possible. Most probably our support is required but we are happy to help in these kind of scenarios.
13+
14+
### Will YAKE support the Gardener operator at some day?
15+
16+
Most likely, yes. As of writing this, there are no clear plans to integrate the Gardener operator into YAKE, as this would introduce a complex migration path. However, we are always willing to improve YAKE and once the time is ready, the Gardener operator will be introduced to manage the garden in YAKE.

‎docs/versioned_docs/version-1.112.x/guides/_category_.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Guides",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Advanced topics and guides"
7+
}
8+
}

‎docs/versioned_docs/version-1.112.x/guides/installation.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# Installation
6+
7+
The process of installing YAKE can differ slightly depending on your kubernetes environment. So this section will be expanded to include more providers over time.
8+
9+
[AKS](https://github.com/YAKEcloud/yake-install-examples/tree/main/azure)

0 commit comments

Comments
 (0)