Guided Tour 4 (gardener#660)

* Import parameter examples

* Import parameter

* Readme files

docs/README.md

@@ -36,6 +36,10 @@
 - [Installation and Configuration of Landscaper](gettingstarted/install-landscaper-controller.md)
 - [Landscaper Service](gettingstarted/install-landscaper-service.md)
 
+## Guided Tour
+
+- [Guided Tour](guided-tour/README.md)
+
 ## Motivation
 
 - [What is Landscaper?](motivation/motivation.md)

docs/guided-tour/.docnames

@@ -0,0 +1,3 @@
+{
+  "header": "Guided Tour"
+}

docs/guided-tour/README.md

@@ -45,6 +45,14 @@ In this tour, you will learn about the different Landscaper features by simple e
 
 [9. Helm Chart Resources in the Component Descriptor](./blueprints/helm-chart-resource)
 
+[10. Echo Server Example](./blueprints/echo-server)
+
+## Imports and Exports
+
+[11. Import Parameters](./import-export/import-parameters)
+
+[12. Import Data Mappings](./import-export/import-data-mappings)
+
 
 <!--
 Delete without uninstall

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

@@ -23,8 +23,9 @@ spec:
           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
+            - name: cluster   # name of the import parameter
+              type: target
+              targetType: landscaper.gardener.cloud/kubernetes-cluster
 
           deployExecutions:
             - name: default

docs/guided-tour/basics/multiple-deployitems/installation/installation.yaml

@@ -27,8 +27,10 @@ spec:
           # Define two import parameters
           imports:
             - name: cluster-1
+              type: target
               targetType: landscaper.gardener.cloud/kubernetes-cluster
             - name: cluster-2
+              type: target
               targetType: landscaper.gardener.cloud/kubernetes-cluster
 
           deployExecutions:

docs/guided-tour/basics/upgrade/installation/installation-1.0.0.yaml

@@ -23,8 +23,9 @@ spec:
           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
+            - name: cluster   # name of the import parameter
+              type: target
+              targetType: landscaper.gardener.cloud/kubernetes-cluster
 
           deployExecutions:
             - name: default

docs/guided-tour/basics/upgrade/installation/installation-1.0.1.yaml

@@ -23,8 +23,9 @@ spec:
           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
+            - name: cluster   # name of the import parameter
+              type: target
+              targetType: landscaper.gardener.cloud/kubernetes-cluster
 
           deployExecutions:
             - name: default

docs/guided-tour/blueprints/echo-server/README.md

@@ -0,0 +1,93 @@
+# Echo Server Example
+
+In this example, we use the Landscaper to deploy an echo server.
+
+For prerequisites, see [here](../../README.md#prerequisites-and-basic-definitions).
+
+The example uses the following resources:
+
+- a blueprint, which you can find [locally](./blueprint), and 
+  uploaded [in an OCI registry](https://eu.gcr.io/gardener-project/landscaper/examples/blueprints/guided-tour/echo-server),
+- a Helm chart which you can also find [locally](./blueprint) and
+  uploaded [in an OCI registry](https://eu.gcr.io/gardener-project/landscaper/examples/charts/guided-tour/echo-server),
+- the Docker image [hashicorp/http-echo](https://hub.docker.com/r/hashicorp/http-echo) as an external resource.
+
+All these resources are listed in the [component descriptor](./component-descriptor.yaml). 
+It is an advantage to have them all in one place, in a standard format. 
+Otherwise, you would have to search images spread somewhere in charts, perhaps even mixed with some templating.
+Moreover, the component descriptor can be used by other tools for example for transport or signing. 
+
+
+## OCI Image Resource in the Component Descriptor
+
+The [echo-server Helm chart](./chart/echo-server) in this example consists of a `Deployment` and a `Service`.
+The `Deployment` uses a container image. However, instead of a hard-coded image reference in
+the [deployment.yaml](./chart/echo-server/templates/deployment.yaml), we rather maintain the image reference in the
+component descriptor. In detail, the connection is the following:
+
+- The [component descriptor](./component-descriptor.yaml) contains a resource with name `echo-server-image` and a
+  reference to the actual image:
+
+  ```yaml
+  name: echo-server-image
+  type: ociImage
+  version: v0.2.3
+  relation: external
+  access:
+    type: ociRegistry
+    imageReference: hashicorp/http-echo:0.2.3
+  ```
+
+- The [blueprint](./blueprint/blueprint.yaml) contains a template for a `DeployItem`. Part of this is a 
+  section `values` for the Helm values. During the templating, we read the entry `echo-server-image` of the 
+  component descriptor, extract the field `access.imageReference`, and write it into the section with Helm values: 
+
+  ```yaml
+  values:
+    {{ $imageResource := getResource .cd "name" "echo-server-image" }}
+    image: {{ $imageResource.access.imageReference }}
+  ```
+
+  After the templating, the resulting `DeployItem` contains the image reference in its `values` section:
+
+  ```yaml
+  values:
+    image: hashicorp/http-echo:0.2.3
+  ```
+
+- Finally, the [deployment.yaml](./chart/echo-server/templates/deployment.yaml) of the chart takes the image from the 
+  Helm values:
+
+  ```yaml
+  containers:
+    - image: {{ .Values.image }}
+  ```
+
+
+## Procedure
+
+The procedure to install the helm chart with Landscaper is as follows:
+
+1. Add the kubeconfig of your target cluster to your [target.yaml](installation/target.yaml).
+
+2. On the Landscaper resource cluster, create namespace `example` and apply
+   the [context.yaml](./installation/context.yaml),
+   the [target.yaml](installation/target.yaml), and the [installation.yaml](installation/installation.yaml):
+
+   ```shell
+   kubectl create ns example
+   kubectl apply -f <path to context.yaml>
+   kubectl apply -f <path to target.yaml>
+   kubectl apply -f <path to installation.yaml>
+   ```
+
+3. To try out the echo server, first define a port forwarding on the target cluster:
+
+   ```shell
+   kubectl port-forward -n example service/echo-server 8080:80
+   ```
+
+   Then open `localhost:8080` in a browser.  
+
+   The response should be "hello world", which is the text defined
+   in the [values.yaml](./chart/echo-server/values.yaml) of the chart.

docs/guided-tour/blueprints/echo-server/blueprint/blueprint.yaml

@@ -0,0 +1,34 @@
+apiVersion: landscaper.gardener.cloud/v1alpha1
+kind: Blueprint
+jsonSchema: "https://json-schema.org/draft/2019-09/schema"
+
+imports:
+  - name: cluster  # name of the import parameter
+    type: target
+    targetType: landscaper.gardener.cloud/kubernetes-cluster
+
+deployExecutions:
+  - name: default
+    type: GoTemplate
+    template: |
+      deployItems:
+        - name: default-deploy-item
+          type: landscaper.gardener.cloud/helm
+
+          target:
+            import: cluster   # "cluster" is the name of an import parameter
+
+          config:
+            apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1
+            kind: ProviderConfiguration
+            name: echo-server
+            namespace: example
+            createNamespace: true
+
+            chart:
+              {{ $chartResource := getResource .cd "name" "echo-server-chart" }}
+              ref: {{ $chartResource.access.imageReference }}
+
+            values:
+              {{ $imageResource := getResource .cd "name" "echo-server-image" }}
+              image: {{ $imageResource.access.imageReference }}

docs/guided-tour/blueprints/echo-server/chart/echo-server/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+appVersion: 1.0.0
+description: Echo server chart
+name: echo-server
+type: application
+version: 1.0.0

docs/guided-tour/blueprints/echo-server/chart/echo-server/templates/deployment.yaml

@@ -0,0 +1,23 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}
+  namespace: {{ .Release.Namespace }}
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: echo
+  template:
+    metadata:
+      labels:
+        app: echo
+    spec:
+      containers:
+        - image: {{ .Values.image }}
+          imagePullPolicy: IfNotPresent
+          name: echo
+          args:
+            - -text="{{ .Values.text }}"
+          ports:
+            - containerPort: 5678

docs/guided-tour/blueprints/echo-server/chart/echo-server/templates/service.yaml

@@ -0,0 +1,12 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}
+  namespace: {{ .Release.Namespace }}
+spec:
+  selector:
+    app: echo
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 5678

docs/guided-tour/blueprints/echo-server/chart/echo-server/values.yaml

@@ -0,0 +1,2 @@
+image: hashicorp/http-echo:0.2.0
+text: hello world

docs/guided-tour/blueprints/echo-server/commands/push-blueprint.sh

@@ -0,0 +1,21 @@
+#!/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)/.."
+BLUEPRINT_DIR="${COMPONENT_DIR}/blueprint"
+OCI_ARTIFACT_REF="eu.gcr.io/gardener-project/landscaper/examples/blueprints/guided-tour/echo-server:1.0.0"
+
+landscaper-cli blueprints push "${OCI_ARTIFACT_REF}" "${BLUEPRINT_DIR}"

docs/guided-tour/blueprints/echo-server/commands/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=<your access token>
+
+COMPONENT_DIR="$(dirname $0)/.."
+
+helm package "${COMPONENT_DIR}/chart/echo-server" -d "${COMPONENT_DIR}/commands"
+
+helm registry login eu.gcr.io -u oauth2accesstoken -p "${ACCESS_TOKEN}"
+
+helm push "${COMPONENT_DIR}/commands/echo-server-1.0.0.tgz" oci://eu.gcr.io/gardener-project/landscaper/examples/charts/guided-tour

docs/guided-tour/blueprints/echo-server/commands/push-component-descriptor.sh

@@ -0,0 +1,35 @@
+#!/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 is the is the path to the directory that contains the component-descriptor.yaml and resources.yaml
+COMPONENT_DIR="$(dirname $0)/.."
+
+# TRANSPORT_FILE is the path to the transport tar file that will be created and pushed to the oci registry
+TRANSPORT_FILE=${COMPONENT_DIR}/commands/transport.tar
+
+echo "Component directory: ${COMPONENT_DIR}"
+echo "Transport file:      ${TRANSPORT_FILE}"
+
+if [ -f "${TRANSPORT_FILE}" ]; then
+  echo "Removing old transport file"
+  rm "${TRANSPORT_FILE}"
+fi
+
+echo "Creating transport file"
+landscaper-cli component-cli component-archive "${COMPONENT_DIR}" "${TRANSPORT_FILE}"
+
+echo "Pushing transport file to oci registry"
+component-cli ctf push "${TRANSPORT_FILE}"

docs/guided-tour/blueprints/echo-server/component-descriptor.yaml

@@ -0,0 +1,38 @@
+meta:
+  schemaVersion: 'v2'
+component:
+  name: 'github.com/gardener/landscaper-examples/guided-tour/echo-server'
+  version: '1.0.0'
+
+  repositoryContexts:
+    - type: 'ociRegistry'
+      baseUrl: 'eu.gcr.io/gardener-project/landscaper/examples'
+
+  provider: 'internal'
+
+  componentReferences: []
+
+  sources: []
+
+  resources:
+    - name: blueprint
+      type: blueprint
+      version: 1.0.0
+      relation: external
+      access:
+        type: ociRegistry
+        imageReference: eu.gcr.io/gardener-project/landscaper/examples/blueprints/guided-tour/echo-server:1.0.0
+    - name: echo-server-chart
+      type: helm.io/chart
+      version: 1.0.0
+      relation: external
+      access:
+        type: ociRegistry
+        imageReference: eu.gcr.io/gardener-project/landscaper/examples/charts/guided-tour/echo-server:1.0.0
+    - name: echo-server-image
+      type: ociImage
+      version: v0.2.3
+      relation: external
+      access:
+        type: ociRegistry
+        imageReference: hashicorp/http-echo:0.2.3

docs/guided-tour/blueprints/echo-server/installation/context.yaml

@@ -0,0 +1,9 @@
+apiVersion: landscaper.gardener.cloud/v1alpha1
+kind: Context
+metadata:
+  name: landscaper-examples
+  namespace: example
+
+repositoryContext:
+  baseUrl: eu.gcr.io/gardener-project/landscaper/examples
+  type: ociRegistry