diff --git a/docs/concepts/Glossary.md b/docs/concepts/Glossary.md index 2409b58e1..e3147972b 100644 --- a/docs/concepts/Glossary.md +++ b/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. diff --git a/docs/guided-tour/README.md b/docs/guided-tour/README.md new file mode 100644 index 000000000..ffb657d16 --- /dev/null +++ b/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) + + diff --git a/docs/guided-tour/basics/manifest-deployer/README.md b/docs/guided-tour/basics/manifest-deployer/README.md new file mode 100644 index 000000000..b9727164a --- /dev/null +++ b/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 + kubectl apply -f + ``` + +3. Wait until the Installation is in phase `Succeeded` and check that the ConfigMap was created. diff --git a/docs/guided-tour/basics/manifest-deployer/installation/installation.yaml b/docs/guided-tour/basics/manifest-deployer/installation/installation.yaml new file mode 100644 index 000000000..f9f0e9078 --- /dev/null +++ b/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 diff --git a/docs/guided-tour/basics/manifest-deployer/installation/target.yaml b/docs/guided-tour/basics/manifest-deployer/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/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 # + ... # diff --git a/docs/guided-tour/basics/upgrade/README.md b/docs/guided-tour/basics/upgrade/README.md new file mode 100644 index 000000000..078a0ab60 --- /dev/null +++ b/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 + kubectl apply -f + ``` + +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 + ``` + + 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 + ``` diff --git a/docs/guided-tour/basics/upgrade/chart/hello-world/Chart.yaml b/docs/guided-tour/basics/upgrade/chart/hello-world/Chart.yaml new file mode 100644 index 000000000..bec06467f --- /dev/null +++ b/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 diff --git a/docs/guided-tour/basics/upgrade/chart/hello-world/templates/secret.yaml b/docs/guided-tour/basics/upgrade/chart/hello-world/templates/secret.yaml new file mode 100644 index 000000000..8d3c44150 --- /dev/null +++ b/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 }} diff --git a/docs/guided-tour/basics/upgrade/chart/hello-world/values.yaml b/docs/guided-tour/basics/upgrade/chart/hello-world/values.yaml new file mode 100644 index 000000000..af1cd4254 --- /dev/null +++ b/docs/guided-tour/basics/upgrade/chart/hello-world/values.yaml @@ -0,0 +1 @@ +testData: default-data diff --git a/docs/guided-tour/basics/upgrade/commands/apply-target-and-installation.sh b/docs/guided-tour/basics/upgrade/commands/apply-target-and-installation.sh new file mode 100755 index 000000000..f24dc9615 --- /dev/null +++ b/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}" diff --git a/docs/guided-tour/basics/upgrade/commands/create-and-push-chart.sh b/docs/guided-tour/basics/upgrade/commands/create-and-push-chart.sh new file mode 100755 index 000000000..102f454d9 --- /dev/null +++ b/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 diff --git a/docs/guided-tour/basics/upgrade/commands/settings b/docs/guided-tour/basics/upgrade/commands/settings new file mode 100644 index 000000000..af44c1808 --- /dev/null +++ b/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=... diff --git a/docs/guided-tour/basics/upgrade/commands/upgrade-installation.sh b/docs/guided-tour/basics/upgrade/commands/upgrade-installation.sh new file mode 100755 index 000000000..2fa09fe20 --- /dev/null +++ b/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}" diff --git a/docs/guided-tour/basics/upgrade/installation/installation-1.0.0.yaml b/docs/guided-tour/basics/upgrade/installation/installation-1.0.0.yaml new file mode 100644 index 000000000..cc5ca637b --- /dev/null +++ b/docs/guided-tour/basics/upgrade/installation/installation-1.0.0.yaml @@ -0,0 +1,48 @@ +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/helm + + target: + import: cluster # "cluster" is the name of an import parameter + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 + values: + testData: hello diff --git a/docs/guided-tour/basics/upgrade/installation/installation-1.0.1.yaml b/docs/guided-tour/basics/upgrade/installation/installation-1.0.1.yaml new file mode 100644 index 000000000..92cbb455e --- /dev/null +++ b/docs/guided-tour/basics/upgrade/installation/installation-1.0.1.yaml @@ -0,0 +1,48 @@ +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/helm + + target: + import: cluster # "cluster" is the name of an import parameter + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.1 + values: + testData: hello diff --git a/docs/guided-tour/basics/upgrade/installation/target.yaml b/docs/guided-tour/basics/upgrade/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/docs/guided-tour/basics/upgrade/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 # + ... # diff --git a/docs/guided-tour/error-handling/delete-error/README.md b/docs/guided-tour/error-handling/delete-error/README.md new file mode 100644 index 000000000..88bab78d6 --- /dev/null +++ b/docs/guided-tour/error-handling/delete-error/README.md @@ -0,0 +1,71 @@ +# Handling a Delete Error + +In this example, we deploy again the Helm chart of the hello-world example and then delete it again whereby we provoke +an error by removing the target before. + +## Procedure + +First create the Target and the Installation again: + +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 + kubectl apply -f + ``` + +## Delete the Target and the Installation + +In the next step we delete the target `my-cluster`: + +```shell +kubectl delete target -n example my-cluster +``` + +Now when we delete the Installation, there is no access information of the target cluster available from where +the Helm chart should be removed and therefore the deletion of the Installation fails: + +```shell +kubectl delete installation -n example hello-world +``` + +Now it requires some time until the timeout occurs and the Installation fails, i.e. `phase: DeletionFailed`. You could +speed this up by setting the interrupt annotation: + +```shell +kubectl annotate installation -n example hello-world landscaper.gardener.cloud/operation=interrupt +``` + +## Resolve the failed Installation + +### Recreate the Target + +The usual way to resolve the failed Installation is to recreate the target and re-trigger the deletion of the +installation by setting the `reconcile` annotation: + +```shell +kubectl apply -f +kubectl annotate installation -n example hello-world landscaper.gardener.cloud/operation=reconcile +``` + +Now the installation is gone and the deployed Helm chart was uninstalled. + +### Force Delete + +If it is not possible to resolve the problems and it is ok that the deployed Helm chart is not uninstalled, +you could use the [landscaper-cli](https://github.com/gardener/landscapercli) to remove the installation. For example, +this is the preferred solution if the target cluster does not exist anymore. You achieve this with the following +command: + +```shell +landscaper-cli installations force-delete -n example hello-world +``` + +It is not recommended to use this approach, if you have a successful Installation and want to remove it without +uninstalling the deployed components on the target cluster. In such a situation use the annotation +`landscaper.gardener.cloud/delete-without-unstall: true`. + diff --git a/docs/guided-tour/error-handling/delete-error/commands/apply-target-and-installation.sh b/docs/guided-tour/error-handling/delete-error/commands/apply-target-and-installation.sh new file mode 100755 index 000000000..83d38466a --- /dev/null +++ b/docs/guided-tour/error-handling/delete-error/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.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}" diff --git a/docs/guided-tour/error-handling/delete-error/commands/settings b/docs/guided-tour/error-handling/delete-error/commands/settings new file mode 100644 index 000000000..af44c1808 --- /dev/null +++ b/docs/guided-tour/error-handling/delete-error/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=... diff --git a/docs/guided-tour/error-handling/delete-error/installation/installation.yaml b/docs/guided-tour/error-handling/delete-error/installation/installation.yaml new file mode 100644 index 000000000..be4cc5e59 --- /dev/null +++ b/docs/guided-tour/error-handling/delete-error/installation/installation.yaml @@ -0,0 +1,48 @@ +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 + target: my-cluster + + blueprint: + inline: + filesystem: + blueprint.yaml: | + apiVersion: landscaper.gardener.cloud/v1alpha1 + kind: Blueprint + jsonSchema: "https://json-schema.org/draft/2019-09/schema" + + imports: # yaml structure fixed + - name: cluster + 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 + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 + values: + testData: hello diff --git a/docs/guided-tour/error-handling/delete-error/installation/target.yaml b/docs/guided-tour/error-handling/delete-error/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/docs/guided-tour/error-handling/delete-error/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 # + ... # diff --git a/docs/guided-tour/error-handling/immediate-error/README.md b/docs/guided-tour/error-handling/immediate-error/README.md new file mode 100644 index 000000000..02b5b5a00 --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/README.md @@ -0,0 +1,49 @@ +# Handling an Immediate Error + +In this example, we deploy again the Helm chart of the hello-world example. +To illustrate the error handling, we introduced an error in the Installation: a `:` is missing in the imports section +of the blueprint in the [Installation](./installation/installation.yaml). + + +## Procedure + +In this example we create a Target custom resource, containing the access information for the target cluster and an +Installation custom resource containing the instructions to deploy our example Helm chart. + +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 + kubectl apply -f + ``` + +## Inspect the Result + +This time, the Installation will fail due to the invalid blueprint. + +```yaml +status: + lastError: + message: 'unable to decode blueprint definition from inline defined blueprint.yaml: line 6: could not find expected '':''' + ... + phase: Failed +``` + +## Deploy the fixed Installation + +You can find a fixed version of the Installation in +[installation/installation-fixed.yaml](./installation/installation-fixed.yaml). + +Deploy this version: + +```shell +kubectl apply -f +``` + +Note that this fixed version already contains the annotation `landscaper.gardener.cloud/operation: reconcile`, so +that Landscaper will start processing it. After some time, the phase of the Installation should be `Succeeded` and +the ConfigMap deployed by the Helm chart should exist on the target cluster. diff --git a/docs/guided-tour/error-handling/immediate-error/commands/apply-target-and-installation.sh b/docs/guided-tour/error-handling/immediate-error/commands/apply-target-and-installation.sh new file mode 100755 index 000000000..83d38466a --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/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.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}" diff --git a/docs/guided-tour/error-handling/immediate-error/commands/settings b/docs/guided-tour/error-handling/immediate-error/commands/settings new file mode 100644 index 000000000..af44c1808 --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/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=... diff --git a/docs/guided-tour/error-handling/immediate-error/installation/installation-fixed.yaml b/docs/guided-tour/error-handling/immediate-error/installation/installation-fixed.yaml new file mode 100644 index 000000000..be4cc5e59 --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/installation/installation-fixed.yaml @@ -0,0 +1,48 @@ +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 + target: my-cluster + + blueprint: + inline: + filesystem: + blueprint.yaml: | + apiVersion: landscaper.gardener.cloud/v1alpha1 + kind: Blueprint + jsonSchema: "https://json-schema.org/draft/2019-09/schema" + + imports: # yaml structure fixed + - name: cluster + 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 + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 + values: + testData: hello diff --git a/docs/guided-tour/error-handling/immediate-error/installation/installation.yaml b/docs/guided-tour/error-handling/immediate-error/installation/installation.yaml new file mode 100644 index 000000000..084570660 --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/installation/installation.yaml @@ -0,0 +1,48 @@ +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 + target: my-cluster + + blueprint: + inline: + filesystem: + blueprint.yaml: | + apiVersion: landscaper.gardener.cloud/v1alpha1 + kind: Blueprint + jsonSchema: "https://json-schema.org/draft/2019-09/schema" + + imports # invalid yaml, because of missing ":" + - name: cluster + 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 + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 + values: + testData: hello diff --git a/docs/guided-tour/error-handling/immediate-error/installation/target.yaml b/docs/guided-tour/error-handling/immediate-error/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/docs/guided-tour/error-handling/immediate-error/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 # + ... # diff --git a/docs/guided-tour/error-handling/timeout-error/README.md b/docs/guided-tour/error-handling/timeout-error/README.md new file mode 100644 index 000000000..0f795c00b --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/README.md @@ -0,0 +1,135 @@ +# Handling a Timeout Error + +In this example, we try again to deploy the Helm chart of the hello-world example. +To demonstrate another error situation, we have manipulated the [Installation](./installation/installation.yaml). +It references chart version `0.0.9`, which does not exist. + + +## 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 + kubectl apply -f + ``` + +## Inspect the Result + +When the Landscaper processes the Installation, it does not find the Helm chart version `0.0.9` that is referenced +in the Installation. Landscaper considers this as a recoverable error situation. Therefore, the Installation remains in +phase `Progressing`. Landscaper will retry the processing in intervals that become increasingly larger. + +Status of the Installation: + +```yaml +status: + lastError: + message: execution example / hello-world is not finished yet + phase: Progressing +``` + +Starting from the Installation, Landscaper creates further custom resources, namely DeployItems. In the present case +there will be only one DeployItem, that describes the Helm deployment of the hello-world chart. In the status of the +DeployItem we find further information about the error: + +```shell +# Find the name of the DeployItem +▶ kubectl get di -n example +NAME TYPE PHASE +hello-world-default-deploy-item-tslq8 landscaper.gardener.cloud/helm Progressing + +# Display the DeployItem +▶ k get di -n example hello-world-default-deploy-item-tslq8 -o yaml +... +status: + lastError: + message: 'Op: TemplateChart - Reason: GetHelmChart - Message: unable to resolve + chart from "eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:0.0.9": + unable to get manifest: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:0.0.9: + not found' + phase: Progressing +``` + +The Landscaper CLI command `landscaper-cli inst inspect` prints an object tree consisting of the Installation, +and DeployItems, together with status information: + +```shell +▶ landscaper-cli inst inspect -n example hello-world +[🏗️ Progressing] Installation hello-world + Last error: execution example / hello-world is not finished yet + └── [🏗️ Progressing] DeployItem hello-world-default-deploy-item-tslq8 + Last error: Op: TemplateChart - Reason: GetHelmChart - Message: unable to resolve chart from "eu.gcr.io/gardener-project + /landscaper/examples/charts/hello-world:0.0.9": unable to get manifest: + eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:0.0.9: not found +``` + +After a few minutes, the DeployItem and the Installation will fail due to a timeout: + +```shell +▶ landscaper-cli inst inspect -n example hello-world +[❌ Failed] Installation hello-world + └── [❌ Failed] DeployItem hello-world-default-deploy-item-tslq8 + Last error: deployer has not aborted progressing this deploy item within 300 seconds +``` + +
+Actually there are two timeouts. After the first timeout, the "progressing timeout", the DeployItem is being told to +abort the deployment. If it does not do that before the second timeout, the "abort timeout", it fails. +
+ +As a consequence of the failure of the DeployItem, the Installation also goes into a failure state. + + +## Resolving the Error + +Let's resolve the error situation by fixing the Helm chart version in the Installation. There are two cases. + +**Case 1:** The Installation has already failed due to the timeout described above. In this case we can simply apply +the Installation with the fixed Helm chart version. Make sure that the Installation has the annotation +`landscaper.gardener.cloud/operation: reconcile`, otherwise Landscaper will not start processing it. + +**Case 2:** The Installation has not yet failed, but is still in an unfinished phase like `Progressing`. +The point is that Landscaper does not take any change of the Installation spec into account as long as a deployment is +still running. It is incalculable what might happen when one would change an ongoing deployment in the middle of +the processing. Therefore, it is possible to change the Installation spec, but this change will have no effect +before the timeout has occurred. However, if you do not want to wait until the timeout has occurred, +you can **interrupt** the ongoing deployment as described below. + + +## Interrupting a Deployment + +To interrupt the ongoing deployment, add the annotation `landscaper.gardener.cloud/operation: interrupt` to the +Installation: + +```shell +kubectl annotate inst -n example hello-world landscaper.gardener.cloud/operation=interrupt +``` + +Alternatively, you can use the following command of the Landscaper CLI to add this annotation: + +```shell +landscaper-cli inst interrupt -n example hello-world +``` + +**Warning:** Be aware that the interruption just forces the Installation and its DeployItems into a +final phase (`Succeeded`, `Failed`, or `DeleteFailed`). The behaviour concerning for example a Helm installation that +might run at that moment, is not defined. Therefore, you should interrupt a running deployment only if you are sure +that nothing bad can happen. It is not recommended to use this annotation in a productive environment. + +## Deploy the fixed Installation + +Once the Installation is in phase `Failed`, apply the Installation +[installation/installation-fixed.yaml](./installation/installation-fixed.yaml) with the fixed Helm chart version: + +```shell +kubectl apply -f +``` + +Note that this fixed version already contains the annotation `landscaper.gardener.cloud/operation: reconcile`, so +that Landscaper will start processing it. After some time, the phase of the Installation should be `Succeeded` and +the ConfigMap deployed by the Helm chart should exist on the target cluster. diff --git a/docs/guided-tour/error-handling/timeout-error/commands/apply-target-and-installation.sh b/docs/guided-tour/error-handling/timeout-error/commands/apply-target-and-installation.sh new file mode 100755 index 000000000..83d38466a --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/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.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}" diff --git a/docs/guided-tour/error-handling/timeout-error/commands/settings b/docs/guided-tour/error-handling/timeout-error/commands/settings new file mode 100644 index 000000000..af44c1808 --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/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=... diff --git a/docs/guided-tour/error-handling/timeout-error/installation/installation-fixed.yaml b/docs/guided-tour/error-handling/timeout-error/installation/installation-fixed.yaml new file mode 100644 index 000000000..7e8d45520 --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/installation/installation-fixed.yaml @@ -0,0 +1,48 @@ +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 + target: my-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 + 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 + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 # version exists + values: + testData: hello diff --git a/docs/guided-tour/error-handling/timeout-error/installation/installation.yaml b/docs/guided-tour/error-handling/timeout-error/installation/installation.yaml new file mode 100644 index 000000000..2c2b35d8a --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/installation/installation.yaml @@ -0,0 +1,48 @@ +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 + target: my-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 + 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 + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:0.0.9 # version does not exist + values: + testData: hello diff --git a/docs/guided-tour/error-handling/timeout-error/installation/target.yaml b/docs/guided-tour/error-handling/timeout-error/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/docs/guided-tour/error-handling/timeout-error/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 # + ... # diff --git a/docs/guided-tour/hello-world/README.md b/docs/guided-tour/hello-world/README.md new file mode 100644 index 000000000..ea9a031bb --- /dev/null +++ b/docs/guided-tour/hello-world/README.md @@ -0,0 +1,117 @@ +# Hello World Example + +In this example, we use the Landscaper to deploy a Helm chart. + +Our [hello-world Helm chart](chart/hello-world) is minimalistic to concentrate on Landscaper rather than Helm features. +It deploys just a ConfigMap. We have uploaded the chart to a +[public registry](eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0) from where the Landscaper +reads it during the deployment. + +Altogether, there occur three clusters in this example: + +- the **Landscaper Host Cluster**, on which the Landscaper runs; +- the **target cluster**, on which the Helm chart shall be deployed. +- the **Landscaper Resource Cluster**, on which the custom resources are stored that are watched by the Landscaper. + These custom resources define what should be deployed on which target cluster. + +It is possible that some or all of these clusters coincide. + +## Procedure + +In this example we create a Target custom resource, containing the access information for the target cluster and an +Installation custom resource containing the instructions to deploy our example Helm chart. + +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 + kubectl apply -f + ``` + +Alternative (requires the [Landscaper CLI](https://github.com/gardener/landscapercli)): + +1. In the [commands/settings file](./commands/settings), specify + - the path to the kubeconfig of your Landscaper resource cluster and + - the path to the kubeconfig of your target cluster. + +2. Run script [commands/apply-target-and-installation.sh](./commands/apply-target-and-installation.sh). + +## Landscaper Processes the Installation + +After the deployment of the Target and the Installations the Landscaper picks up these resources and start with +the installation of the Helm chart. Note that the Landscaper only starts working on an Installation if it has the +annotation `landscaper.gardener.cloud/operation: reconcile`. Landscaper removes the annotation when it starts processing +the Installation. Later, if you want to process the Installation again, just add the annotation another time. + + +## Inspect the Result + +You can now check the status of the Installation: + +```shell +kubectl get inst -n example hello-world +``` + +The most important field in the status section is the `phase` which should have finally the value `Succeeded` if the +Helm chart was successfully deployed. + +```yaml +status: + phase: Succeeded +``` + +If you have already installed the [Landscaper CLI](https://github.com/gardener/landscapercli), +you can inspect the status of the installation with the following command, executed on the Landscaper resource cluster: + +```shell +landscaper-cli inst inspect -n example hello-world +``` + +On the target cluster, you should find the ConfigMap, that was deployed as part of the Helm chart: + +```shell +kubectl get configmap -n example hello-world +``` + +## Have a look at the Installation + +In this example we created an Installation custom resource containing the instructions to deploy our example Helm chart +a Target custom resource, containing the access information for the target cluster on which the Helm chart should be +deployed. + +The Installation contains two main sections in its `spec`: + +```yaml +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: + ... +``` + +The `imports` section contains the reference to the target object and the `blueprint` section the deploy instructions. + + +## Delete Installation + +You can uninstall the hello-world Helm chart by deleting the Installation from the Landscaper resource cluster: + +```shell +kubectl delete inst -n example hello-world +``` + + +## References + +[Installations](../../usage/Installations.md) + +[Reconcile Annotation](../../usage/Annotations.md#reconcile-annotation) diff --git a/docs/guided-tour/hello-world/chart/hello-world/Chart.yaml b/docs/guided-tour/hello-world/chart/hello-world/Chart.yaml new file mode 100644 index 000000000..1bbaf8212 --- /dev/null +++ b/docs/guided-tour/hello-world/chart/hello-world/Chart.yaml @@ -0,0 +1,6 @@ +apiVersion: v2 +appVersion: 1.0.0 +description: Hello world helm chart +name: hello-world +type: application +version: 1.0.0 diff --git a/docs/guided-tour/hello-world/chart/hello-world/templates/configmap.yaml b/docs/guided-tour/hello-world/chart/hello-world/templates/configmap.yaml new file mode 100644 index 000000000..ac30f8923 --- /dev/null +++ b/docs/guided-tour/hello-world/chart/hello-world/templates/configmap.yaml @@ -0,0 +1,7 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ .Release.Name }} + namespace: {{ .Release.Namespace }} +data: + testData: {{ .Values.testData }} diff --git a/docs/guided-tour/hello-world/chart/hello-world/values.yaml b/docs/guided-tour/hello-world/chart/hello-world/values.yaml new file mode 100644 index 000000000..af1cd4254 --- /dev/null +++ b/docs/guided-tour/hello-world/chart/hello-world/values.yaml @@ -0,0 +1 @@ +testData: default-data diff --git a/docs/guided-tour/hello-world/commands/apply-target-and-installation.sh b/docs/guided-tour/hello-world/commands/apply-target-and-installation.sh new file mode 100755 index 000000000..83d38466a --- /dev/null +++ b/docs/guided-tour/hello-world/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.yaml" --kubeconfig="${LS_DATA_KUBECONFIG}" diff --git a/docs/guided-tour/hello-world/commands/create-and-push-chart.sh b/docs/guided-tour/hello-world/commands/create-and-push-chart.sh new file mode 100755 index 000000000..088f8cffa --- /dev/null +++ b/docs/guided-tour/hello-world/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.0.tgz" oci://eu.gcr.io/gardener-project/landscaper/examples/charts diff --git a/docs/guided-tour/hello-world/commands/settings b/docs/guided-tour/hello-world/commands/settings new file mode 100644 index 000000000..af44c1808 --- /dev/null +++ b/docs/guided-tour/hello-world/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=... diff --git a/docs/guided-tour/hello-world/installation/installation.yaml b/docs/guided-tour/hello-world/installation/installation.yaml new file mode 100644 index 000000000..cc5ca637b --- /dev/null +++ b/docs/guided-tour/hello-world/installation/installation.yaml @@ -0,0 +1,48 @@ +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/helm + + target: + import: cluster # "cluster" is the name of an import parameter + + config: + apiVersion: helm.deployer.landscaper.gardener.cloud/v1alpha1 + kind: ProviderConfiguration + name: hello-world + namespace: example + chart: + ref: eu.gcr.io/gardener-project/landscaper/examples/charts/hello-world:1.0.0 + values: + testData: hello diff --git a/docs/guided-tour/hello-world/installation/target.yaml b/docs/guided-tour/hello-world/installation/target.yaml new file mode 100644 index 000000000..6817010ea --- /dev/null +++ b/docs/guided-tour/hello-world/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 # + ... #