Target Map Documentation (gardener#981)

* target map docu

* target map docu

* target map docu

* target map docu

* target map docu

* target map docu

docs/README.md

@@ -71,7 +71,6 @@
 - [Optimization](usage/Optimization.md)
 - [Repository Context](usage/RepositoryContext.md)
 - [Skipping the Uninstallation of an Application](usage/SkipUninstall.md)
-- [TargetList Imports](usage/TargetLists.md)
 - [TargetSyncs](usage/TargetSyncs.md)
 - [Targets](usage/Targets.md)
 - [Templating](usage/Templating.md)

docs/guided-tour/README.md

@@ -35,7 +35,10 @@ sidebar_position: 1
 
 ## How to follow the Tour
 
-In order to get the most out of it, you should be following the Guided Tour in this sequence:
+The Guided Tour consists of several chapters, some of which build on each other. In order to get the most out of it, 
+you should be following the Guided Tour in this sequence. Another important point is, that this documentation
+is not optimal with respect to getting an overview about the used example resources in the Guided Tour. Therefore,
+it might be better to read it in the [original github repository](https://github.com/gardener/landscaper/tree/master/docs/guided-tour).
 
 ### A Hello World Example
 
@@ -79,6 +82,18 @@ You can find a list of error messages and corresponding solutions [here](./error
 
 [14. Templating: Accessing Component Descriptors ](./templating/components)
 
-### Optimization
+## Target Maps
 
-[15. Optimization Hints ](../usage/Optimization.md)
+[15. Target Maps: Multiple Deploy Items](./target-maps/01-multiple-deploy-items)
+
+[16. Target Maps: Target Map References](./target-maps/02-targetmap-ref)
+
+[17. Target Maps: Multiple Subinstallations](./target-maps/03-multiple-subinst)
+
+[18. Target Maps: Target Map on Subinstallation Level](./target-maps/04-forward-map)
+
+[19. Target Maps: Other Target Map Examples](./target-maps/05-other-examples)
+
+## Optimization
+
+[20. Optimization Hints ](../usage/Optimization.md)

docs/guided-tour/import-export/import-parameters/README.md

@@ -36,13 +36,13 @@ imports:
     type: string
 ```
 
-In general, we distinguish parameters of type `target`, `targetList`, and `data`.
+In general, we distinguish parameters of type `target`, `targetMap`, and `data`.
 
 To define target parameters more detailed, they have a `targetType`. However, currently there is only
 one supported target type, namely `landscaper.gardener.cloud/kubernetes-cluster`. A blueprint can import more than one
 target. For example, the inline blueprint
 [here](../../basics/multiple-deployitems/installation/installation.yaml)
-has two target imports. A parameter of type `targetList` allows to import a list of targets whose length is not 
+has two target imports. A parameter of type `targetMap` allows to import a list of targets whose length is not 
 specified by the blueprint.
 
 To define data parameters more precisely, they have a `schema`, i.e. a json schema that describes the structure 

docs/guided-tour/target-maps/01-multiple-deploy-items/README.md

@@ -0,0 +1,178 @@
+# Multiple Deploy Items Example
+
+In this example, we show how target maps can be used to deploy an artefact to a variable number of target clusters. 
+
+For prerequisites, see [here](../../README.md#prerequisites-and-basic-definitions).
+
+## Example description
+
+This example presents a component, which gets as input a map of targets and a data object containing
+configuration data for every input target. For every input target a DeployItem is created which deploys
+a config map on the target cluster specified by one of the input targets. The data of the config map contains the
+corresponding data provided as another import.
+
+The example component is stored 
+[here](eu.gcr.io/gardener-project/landscaper/examples/component-descriptors/github.com/gardener/guided-tour/targetmaps/guided-tour-multiple-deploy-items). 
+If you want to upload the component to another registry, you can just adapt the [settings](component/commands/settings) 
+file and execute the component build and upload script [here](component/commands/component.sh).
+
+The component itself is specified here:
+  - [component configuration](component/components.yaml)
+  - [blueprints](component/blueprint) 
+
+## Installing the example
+
+The procedure to install example is as follows:
+
+1. On the Landscaper resource cluster create 
+  - namespace `cu-example`
+
+2. On the Landscaper resource cluster, in namespace `cu-example` create
+  - different targets `cluster-blue`, `cluster-green`, `cluster-red`, `cluster-yellow`, `cluster-orange`. 
+    Usually these targets contain access data to different target clusters but for simplicity we use the same target 
+    cluster for all of them.
+  - a Context `landscaper-examples` and a root Installation `multiple-items`
+  - a DataObject `config` containing the data for the different config maps which will be deployed on the different
+    target clusters.
+
+The templates for these resources can be found [here](component/installation) and could be deployed with 
+this [script](component/commands/deploy-k8s-resources.sh). Adapt the [settings](component/commands/settings) file
+such that the entry `TARGET_CLUSTER_KUBECONFIG_PATH` points to the kubeconfig of the target cluster to which the
+config maps should be deployed.
+
+Now you should see a successful installation on your Landscaper resource cluster:
+
+```
+kubectl get inst -n cu-example multiple-items     
+          
+NAME             PHASE       EXECUTION        AGE
+multiple-items   Succeeded   multiple-items   14s
+```
+
+Let's have a deeper look into the resources of the example. The root Installation `multiple-items` contains as import 
+a target map importing three of the five deployed targets. An entry of the target map consists of a logical name (blue, green etc.)
+and the name of the k8s target object (cluster-blue, cluster-green etc.) 
+
+```
+  imports:
+  
+    targets:
+    - name: clusters
+      targetMap:
+        blue: cluster-blue
+        green: cluster-green
+        red: cluster-red
+        
+    data:
+    - dataRef: config
+      name: config
+      
+    ...
+```
+
+Furthermore, the root Installation imports the DataObject `config` which contains the configuration for the different 
+config maps which should be deployed to the different target clusters which looks as follows (see also 
+[here](component/installation/dataobject.yaml.tpl)):
+
+```yaml
+...
+data:
+  blue:
+    color: blue
+    cpu: 100m
+    memory: 100Mi
+  green:
+    color: green
+    cpu: 120m
+    memory: 120Mi
+...
+
+```
+
+The root installation references this [blueprint](component/blueprint/blueprint.yaml) which imports the `config` as well
+as the target map. The Blueprint creates a DeployItem for every target provided by the target map in its
+[deployExecution](component/blueprint/deploy-execution.yaml). Therefore, it iterates over the target map with the 
+following expression:
+
+```
+{{ range $key, $target := .imports.clusters }}
+```
+
+Thereby, the variable `$key` is set on the logical names of the target from the Installation (red, green, blue). 
+This allows 
+
+- to give the DeployItems a stable name `name: di-{{ $key }}` which is important if you change the input targets later, 
+  to logically identify which DeployItems were removed and added.
+- address the corresponding data in the `config` with `{{- index $config $key | toYaml | nindent 14 }}` which should
+  be provided to the config maps on the target clusters. 
+
+On the Landscaper resource cluster you see the three DeployItems each with the corresponding color in its name:
+
+```
+kubectl get di -n cu-example                     
+NAME                            TYPE                                            PHASE       EXPORTREF   AGE
+multiple-items-di-blue-jx5qc    landscaper.gardener.cloud/kubernetes-manifest   Succeeded               2d22h
+multiple-items-di-green-nwj4v   landscaper.gardener.cloud/kubernetes-manifest   Succeeded               2d22h
+multiple-items-di-red-8zn7r     landscaper.gardener.cloud/kubernetes-manifest   Succeeded               2d22h
+```
+
+On the target cluster you see the deployed config maps with the corresponding color in their names:
+
+```
+kubectl get cm -n example                                                          
+NAME                     DATA   AGE
+compose-map-exec-blue    1      21s
+compose-map-exec-green   1      21s
+compose-map-exec-red     1      21s
+```
+
+Every config map contains the right data from the `config` object.
+
+## Updating the Root Installation
+
+Assume you want to update your deployments such that instead of the config maps `compose-map-exec-blue`,
+`compose-map-exec-green` and `compose-map-exec-red`, the config maps `compose-map-exec-blue`,
+`compose-map-exec-red`, `compose-map-exec-yellow` and `compose-map-exec-orange` are deployed. Therefore, you
+just have to adapt the import target map of you root installation as follows:
+
+```
+  imports:
+  
+    targets:
+    - name: clusters
+      targetMap:
+        blue: cluster-blue
+        red: cluster-red
+        yellow: cluster-yellow
+        orange: cluster-orange
+        
+    data:
+    - dataRef: config
+      name: config
+      
+    ...
+```
+
+And you get your intended new set of config maps, whereby the config map `compose-map-exec-green` is deleted:
+
+```
+kubectl get cm -n example                                                          
+NAME                     DATA   AGE
+compose-map-exec-blue    1      21s
+compose-map-exec-red     1      21s
+compose-map-exec-yellow  1      21s
+compose-map-exec-orange  1      21s
+```
+
+An important point in this example is the following. When you are removing a target from the target map of the root 
+Installation, the target itself is not allowed to be removed as long as the corresponding DeployItem is not 
+successfully deleted. This is because the target is still used for accessing the target cluster for the deletion of 
+the installed k8s resources. This is only a problem if you create the DeployItems in the top level blueprint. 
+If you are using Subinstallations to create the DeployItems, this problem does not occur, because the targets are 
+copied into an internal context for the Subinstallations and only deleted after the deletion of the corresponding
+Subinstallations. There are examples in this guided tour presenting such a solution.
+
+## Removal of the test data
+
+You can remove the Installation, the context and targets by first executing [this](component/commands/delete-inst.sh) 
+script to delete the Installation and then [this](component/commands/delete-rest.sh) to remove the rest.

docs/guided-tour/target-maps/01-multiple-deploy-items/component/blueprint/blueprint.yaml

@@ -0,0 +1,21 @@
+apiVersion: landscaper.gardener.cloud/v1alpha1
+kind: Blueprint
+jsonSchema: "https://json-schema.org/draft/2019-09/schema"
+
+imports:
+  - name: clusters
+    type: targetMap
+    targetType: landscaper.gardener.cloud/kubernetes-cluster
+  - name: config
+    type: data
+    schema:
+      type: object
+  - name: namespace
+    type: data
+    schema:
+        type: string
+
+deployExecutions:
+  - name: default
+    type: GoTemplate
+    file: /deploy-execution.yaml

docs/guided-tour/target-maps/01-multiple-deploy-items/component/blueprint/deploy-execution.yaml

@@ -0,0 +1,26 @@
+deployItems:
+{{ $config := .imports.config }}
+{{ $namespace := .imports.namespace }}
+{{ range $key, $target := .imports.clusters }}
+  - name: di-{{ $key }}
+    type: landscaper.gardener.cloud/kubernetes-manifest
+
+    target:
+      import: clusters
+      key: {{ $key }}
+
+    config:
+      apiVersion: manifest.deployer.landscaper.gardener.cloud/v1alpha2
+      kind: ProviderConfiguration
+      updateStrategy: update
+      manifests:
+        - policy: manage
+          manifest:
+            apiVersion: v1
+            kind: ConfigMap
+            metadata:
+              name: multiple-items-{{ $key }}
+              namespace: {{ $namespace }}
+            data:
+              {{- index $config $key | toYaml | nindent 14 }}
+{{ end }}

docs/guided-tour/target-maps/01-multiple-deploy-items/component/commands/component.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+#
+# Copyright (c) 2024 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.
+
+set -o errexit
+set -x
+
+COMPONENT_DIR="$(dirname $0)/.."
+cd "${COMPONENT_DIR}"
+COMPONENT_DIR="$(pwd)"
+echo compdir ${COMPONENT_DIR}
+
+source ${COMPONENT_DIR}/commands/settings
+
+ctf_dir=`mktemp -d`
+
+# This commands adds the components to a ctf (common transport archive), which is a file system representation of a
+# oci registry
+# --create specifies that the ctf file/directory should be created if it does not exist yet
+# --file specifies the target ctf file/directory where the components should be added
+echo "add components"
+ocm add components --create --file $ctf_dir ./components.yaml
+
+# This command transfers the components contained in the specified ctf (here tour-ctf) to another component repository
+# (here, an oci registry)
+# --enforce specifies that already existing components in the target should always be overwritten with the ones
+# from your source
+ocm transfer ctf --enforce $ctf_dir ${REPO_BASE_URL}
+
+## to inspect a specific component, you can use the following command to download into a component archive (a simple file
+## system representation of a single component)
+## this can be done from a remote repository
+# ocm download component ${REPO_BASE_URL}/<component name>:<component version e.g. 1.1.0> -O ../archive

docs/guided-tour/target-maps/01-multiple-deploy-items/component/commands/delete-inst.sh

@@ -0,0 +1,37 @@
+#!/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.
+
+set -o errexit
+
+COMPONENT_DIR="$(dirname $0)/.."
+cd "${COMPONENT_DIR}"
+COMPONENT_DIR="$(pwd)"
+echo compdir ${COMPONENT_DIR}
+
+source ${COMPONENT_DIR}/commands/settings
+
+TMP_DIR=`mktemp -d`
+echo tempdir ${TMP_DIR}
+
+outputFile="${TMP_DIR}/installation.yaml"
+mako-render "${COMPONENT_DIR}/installation/installation.yaml.tpl" \
+  --var namespace="${NAMESPACE}" \
+  --var targetNamespace="${TARGET_NAMESPACE}" \
+  --output-file=${outputFile}
+kubectl delete -f ${outputFile}
+
+
+