Guided Tour (gardener#637)

* Guided tour

* Manifest deployer example

* start with guided tour

Co-authored-by: Achim Weigel <[email protected]>

docs/concepts/Glossary.md

@@ -2,6 +2,10 @@
 
   - [_Aggregated Blueprint_](#aggregated-blueprint)
   - [_Blueprint_](#blueprint)
+  - [_Cluster_](#cluster)
+    - [_Landscaper Host Cluster_](#landscaper-host-cluster)
+    - [_Landscaper Resource Cluster_](#landscaper-resource-cluster)
+    - [_Target Cluster_](#target-cluster)
   - [_Component Descriptor_](#component-descriptor)
   - [_Context_](#context)
   - [_DataObject_](#dataobject)
@@ -17,8 +21,8 @@
     - [Blueprint Import](#blueprint-import)
     - [Installation Import](#installation-import)
   - [_Installation_](#installation)
-  - [_Sibling Installations_](#sibling-installations)
-  - [_Sub-Installation_](#sub-installation)
+    - [_Sibling Installations_](#sibling-installations)
+    - [_Sub-Installation_](#sub-installation)
   - [_SubinstallationExecution_](#subinstallationexecution)
   - [_Target_](#target)
   - [_Template_](#template)
@@ -48,6 +52,27 @@ Blueprints in a nutshell:
 
 [↑](#glossary)
 
+#### _Clusters_
+
+There are 3 different cluster types mentioned throughout the documentation: Landscaper Host Cluster, Landscaper 
+Resource Cluster, Target Cluster
+
+##### Landscaper Host Cluster
+
+The Landscaper Host Cluster, is the cluster on which the Landscaper runs.
+
+##### Landscaper Resource Cluster
+
+The Landscaper Resource Cluster, is the cluster on which custom resources like Targets and Installations can be created,
+that are watched by the Landscaper.
+
+##### Target Cluster
+
+A target cluster is a cluster on which the Landscaper deploys applications. One Landscaper can deploy applications
+to different target clusters.
+
+[↑](#glossary)
+
 #### _Component Descriptor_
   A Component Descriptor contains references and locations to all resources that are used by Landscaper to deploy and install an application.
   Typically, a Component Descriptor is stored in an OCI registry.

docs/guided-tour/README.md

@@ -0,0 +1,34 @@
+# Guided Tour
+
+This document contains a guided tour presenting the different Landscaper features by examples.
+
+Prerequisites:
+- [Running Landscaper instance](docs/gettingstarted/install-landscaper-controller.md)
+
+
+## A Hello World Example
+
+[Hello World Example](./hello-world)
+
+## Basics
+
+[Upgrading the Hello World Example](./basics/upgrade)
+
+[Manifest Deployer Example](./basics/manifest-deployer)
+
+## Recovering from Errors
+
+[Handling an Immediate Error](./error-handling/immediate-error)
+
+[Handling a Timeout Error](./error-handling/timeout-error)
+
+[Handling a Delete Error](./error-handling/delete-error)
+
+<!--
+Delete without uninstall
+Observed generation, jobID, jobIDFinished
+Deploying a blueprint to multiple targets/target list
+Pull secrets for helm chart repo (with and without secret ref)
+context to access oci registry
+timeouts
+-->

docs/guided-tour/basics/manifest-deployer/README.md

@@ -0,0 +1,52 @@
+# Manifest Deployer Example
+
+The Landscaper offers different deployers: 
+
+- the [Helm Deployer](../../../deployer/helm.md)
+- the [Kubernetes Manifest Deployer](../../../deployer/manifest.md), 
+- and the [Container Deployer](../../../deployer/container.md).
+
+We have already used the Helm deployer in the Hello World Example to create a ConfigMap on the target cluster.
+In the present example we show how the same task can be achieved with the Kubernetes manifest deployer.
+The Kubernetes manifest deployer is suitable if you want to deploy some Kubernetes manifests without extra building a 
+Helm chart for them. The Kubernetes manifests to be deployed are directly included in the blueprint of the Installation.
+
+Let's have a look into the blueprint of the [Installation](installation/installation.yaml). It contains one DeployItem:
+
+```yaml
+                deployItems:
+                  - name: default-deploy-item
+                    type: landscaper.gardener.cloud/kubernetes-manifest
+                    config:  
+                      manifests:
+                        - manifest:
+                            apiVersion: v1
+                            kind: ConfigMap
+                            metadata:
+                              name: hello-world
+                              namespace: example
+                            data:
+                              testData: hello
+```
+
+The type `landscaper.gardener.cloud/kubernetes-manifest` tells Landscaper that the manifest deployer 
+should be used to process the DeployItem.
+A DeployItem also contains a `config` section, whose structure depends on the type. In case of the manifest deployer,
+the `config` section contains the list of Kubernetes manifest that should be applied to the target cluster. 
+In the present example, this list contains the Kubernetes manifest of the ConfigMap that we want to create. 
+
+
+## Procedure
+
+1. Insert in file [target.yaml](installation/target.yaml) the kubeconfig of your target cluster.
+
+2. On the Landscaper resource cluster, create namespace `example` and apply 
+   the [target.yaml](installation/target.yaml) and the [installation.yaml](installation/installation.yaml):
+
+   ```shell
+   kubectl create ns example
+   kubectl apply -f <path to target.yaml>
+   kubectl apply -f <path to installation.yaml>
+   ```
+
+3. Wait until the Installation is in phase `Succeeded` and check that the ConfigMap was created.

docs/guided-tour/basics/manifest-deployer/installation/installation.yaml

@@ -0,0 +1,53 @@
+apiVersion: landscaper.gardener.cloud/v1alpha1
+kind: Installation
+metadata:
+  name: hello-world
+  namespace: example
+  annotations:
+    landscaper.gardener.cloud/operation: reconcile
+
+spec:
+
+  # Set values for the import parameters of the blueprint
+  imports:
+    targets:
+      - name: cluster        # name of an import parameter of the blueprint
+        target: my-cluster   # name of the Target custom resource containing the kubeconfig of the target cluster
+
+  blueprint:
+    inline:
+      filesystem:
+        blueprint.yaml: |
+          apiVersion: landscaper.gardener.cloud/v1alpha1
+          kind: Blueprint
+          jsonSchema: "https://json-schema.org/draft/2019-09/schema"
+
+          imports:
+            - name: cluster                                             # name of the import parameter
+              targetType: landscaper.gardener.cloud/kubernetes-cluster  # type of the import parameter
+
+          deployExecutions:
+            - name: default
+              type: GoTemplate
+              template: |
+                deployItems:
+                  - name: default-deploy-item
+                    type: landscaper.gardener.cloud/kubernetes-manifest
+          
+                    target:
+                      import: cluster   # "cluster" is the name of an import parameter
+          
+                    config:
+                      apiVersion: manifest.deployer.landscaper.gardener.cloud/v1alpha2
+                      kind: ProviderConfiguration
+                      updateStrategy: update
+                      manifests:
+                        - policy: manage
+                          manifest:
+                            apiVersion: v1
+                            kind: ConfigMap
+                            metadata:
+                              name: hello-world
+                              namespace: example
+                            data:
+                              testData: hello

docs/guided-tour/basics/manifest-deployer/installation/target.yaml

@@ -0,0 +1,12 @@
+apiVersion: landscaper.gardener.cloud/v1alpha1
+kind: Target
+metadata:
+  name: my-cluster
+  namespace: example
+spec:
+  type: landscaper.gardener.cloud/kubernetes-cluster
+  config:
+    kubeconfig: |
+      apiVersion: v1  # <-------------------------- replace with your kubeconfig
+      kind: Config    #
+      ...             #

docs/guided-tour/basics/upgrade/README.md

@@ -0,0 +1,46 @@
+# Upgrading the Hello World Example
+
+In this example, we start by deploying the hello-world Helm chart in its original version `1.0.0`. 
+Afterwards, we will upgrade the Installation so that it deploys the newer version `1.0.1` of the chart.
+
+You can find the new Helm chart [here](chart/hello-world). It replaces the ConfigMap of the original chart version by
+a Secret. We have uploaded the new chart version to the
+[public registry](eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.1).
+
+
+## Procedure
+
+First, we deploy the original hello-world scenario:
+
+1. Insert in file [target.yaml](installation/target.yaml) the kubeconfig of your target cluster.
+
+2. On the Landscaper resource cluster, create namespace `example` and apply 
+   the [target.yaml](installation/target.yaml) and the original Installation 
+   [installation-1.0.0.yaml](installation/installation-1.0.0.yaml):
+
+   ```shell
+   kubectl create ns example
+   kubectl apply -f <path to target.yaml>
+   kubectl apply -f <path to installation-1.0.0.yaml>
+   ```
+
+3. Wait until the Installation is in phase `Succeeded` and check that the ConfigMap of the original Helm chart
+   was created.
+
+4. Upgrade the Installation by applying [installation-1.0.1.yaml](installation/installation-1.0.1.yaml)
+   The upgraded Installation references the newer version `1.0.1` of the hello-world Helm chart, which deploys a Secret
+   instead of a ConfigMap.
+
+   ```shell
+   kubectl apply -f <path to installation-1.0.1.yaml>
+   ```
+
+   Note that the upgraded Installation has the annotation `landscaper.gardener.cloud/operation: reconcile`. Without this
+   annotation, Landscaper will not start processing the Installation.
+
+5. Wait until the Installation is again in phase `Succeeded`. The ConfigMap that was deployed by the old chart version 
+   should no longer exist. Instead, there should now be a Secret deployed by the new chart version:
+
+   ```shell
+   kubectl get secret -n example hello-world
+   ```

docs/guided-tour/basics/upgrade/chart/hello-world/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+appVersion: 1.0.1
+description: Hello world helm chart
+name: hello-world
+type: application
+version: 1.0.1

docs/guided-tour/basics/upgrade/chart/hello-world/templates/secret.yaml

@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Release.Name }}
+  namespace: {{ .Release.Namespace }}
+stringData:
+  testData: {{ .Values.testData }}

docs/guided-tour/basics/upgrade/chart/hello-world/values.yaml

@@ -0,0 +1 @@
+testData: default-data

docs/guided-tour/basics/upgrade/commands/apply-target-and-installation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+#
+# Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+COMPONENT_DIR="$(dirname $0)/.."
+
+source ${COMPONENT_DIR}/commands/settings
+
+# create namespace "example" on the landscaper data cluster
+kubectl create ns example --kubeconfig="${LS_DATA_KUBECONFIG}"
+
+# create target
+landscaper-cli targets create kubernetes-cluster \
+  --name my-cluster \
+  --namespace example \
+  --target-kubeconfig "${TARGET_KUBECONFIG}" \
+  | kubectl apply -f - --kubeconfig="${LS_DATA_KUBECONFIG}"
+
+# create installation
+kubectl apply -f "${COMPONENT_DIR}/installation/installation-1.0.0.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}"

docs/guided-tour/basics/upgrade/commands/create-and-push-chart.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+#
+# Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# Get an access token:
+# gcloud auth login
+# gcloud auth print-access-token
+ACCESS_TOKEN=...
+
+COMPONENT_DIR="$(dirname $0)/.."
+
+helm package "${COMPONENT_DIR}/chart/hello-world" -d "${COMPONENT_DIR}/commands"
+
+helm registry login eu.gcr.io -u oauth2accesstoken -p "${ACCESS_TOKEN}"
+
+helm push "${COMPONENT_DIR}/commands/hello-world-1.0.1.tgz" oci://eu.gcr.io/gardener-project/landscaper/examples/charts

docs/guided-tour/basics/upgrade/commands/settings

@@ -0,0 +1,5 @@
+# Path to the kubeconfig of the Landscaper data cluster
+LS_DATA_KUBECONFIG=...
+
+# Path to the kubeconfig of the target cluster
+TARGET_KUBECONFIG=...

docs/guided-tour/basics/upgrade/commands/upgrade-installation.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+#
+# Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+COMPONENT_DIR="$(dirname $0)/.."
+
+source ${COMPONENT_DIR}/commands/settings
+
+
+# upgrade installation
+kubectl apply -f "${COMPONENT_DIR}/installation/installation-1.0.1.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}"